Merge pull request #631 from vorburger/ugd_develop_vorburger
GSoC UGD API Doc proposal (for discussion & review)
This commit is contained in:
Vishwas Babu A J
@@ -19856,6 +19856,348 @@ GET https://DomainName/api/v1/search?query=000000111
|
||||
</div>
|
||||
</div>
|
||||
<!-- ends Search API docs-->
|
||||
|
||||
|
||||
<!-- start of clients api docs -->
|
||||
<a id="templates" name="clients" class="old-syle-anchor"> </a>
|
||||
<div class="method-section">
|
||||
<div class="method-description">
|
||||
<h3>Templates</h3>
|
||||
<p>Templates are used for end-user features such as custom user defined document generation (AKA UGD). They are based on <a href="http://mustache.github.io/">{{ moustache }} templates</a>. Think of them as a sort of built-in "mail merge" functionality.</p>
|
||||
|
||||
<p>User Generated Documents (and other types of templates) can aggregate data from several Mifos X back-end API calls via <b>mappers</b>. Mappers can even access non-Mifos X REST services from other servers. UGDs can render such data in tables, show images, etc. <i>TBD: Please have a look at some of the Example UGDs included in Mifos X (or <a href="https://mifosforge.jira.com/wiki/display/RES/UGD_FinalDoc">the Wiki page</a>, for now.).</i></p>
|
||||
|
||||
<p>Templates can be assigned to an entity like <b>client</b> or <b>loan</b> and be of a typ like <b>document</b>. The entity and type of a template is only there for the convenience of user agents (UIs), in order to know where to show templates for the user (i.e. which tab). The Template Engine back-end runner does not actually need this metadata.</p>
|
||||
<table class=matrixHeading>
|
||||
<tr class="matrixHeadingBG">
|
||||
<td><div class="mifosXHeading2">Field Descriptions</div></td>
|
||||
</tr>
|
||||
<tr class=alt>
|
||||
<td>name</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class=fielddesc>Describes the document which will be created.
|
||||
It must be unique and appears listed in a tab at the assigned entity. </td>
|
||||
</tr>
|
||||
<tr class=alt>
|
||||
<td>type</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class=fielddesc>
|
||||
For now only the type document is supported.
|
||||
In a next version templates may be created for e-mails oder SMS.
|
||||
</td>
|
||||
</tr>
|
||||
<tr class=alt>
|
||||
<td>entity</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class=fielddesc>
|
||||
Indicates the primary resource reference.
|
||||
Templates may be filtered by entity and type so the relevant templates may be listed at the belonging position.
|
||||
</td>
|
||||
</tr>
|
||||
<tr class=alt>
|
||||
<td>text</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class=fielddesc>
|
||||
The actual template which may be any html-text containing mustache tags.
|
||||
</td>
|
||||
</tr>
|
||||
<tr class=alt>
|
||||
<td>mappers</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td class=fielddesc>
|
||||
By default one mapper is assigned to the template depending on the entity.
|
||||
Mappers are used to create requests and get tags wich may be used in the template.
|
||||
Also mappery are in order and may depend on the previous mappers.
|
||||
For now mappers expect a response in JSON or plain/text.
|
||||
JSON contains the keys and the values.
|
||||
If the response is plain/text it can be accessed by {{$mapperskey.src}}
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<a id="clients_template" name="clients_template" class="old-syle-anchor"> </a>
|
||||
<div class="method-section">
|
||||
<div class="method-description">
|
||||
<h4>Retrieve Template Details Template</h4>
|
||||
<p>This is a convenience resource. It can be useful when
|
||||
building maintenance user interface screens for templates.
|
||||
The template data returned consists of any or all of:
|
||||
</p>
|
||||
<h5>Arguments</h5>
|
||||
<dl class="argument-list">
|
||||
<dt>name</dt>
|
||||
<dd>
|
||||
String
|
||||
</dd>
|
||||
<dt>entity</dt>
|
||||
<dd>
|
||||
String
|
||||
</dd>
|
||||
<dt>type</dt>
|
||||
<dd>
|
||||
String
|
||||
</dd>
|
||||
<dt>text</dt>
|
||||
<dd>
|
||||
String <span>optional</span>
|
||||
</dd>
|
||||
<dt>mappers</dt>
|
||||
<dd>
|
||||
Mapper <span>optional</span>
|
||||
</dd>
|
||||
</dl>
|
||||
<p>Example Request:</p>
|
||||
<div class=apiClick>templates/template</div>
|
||||
</div>
|
||||
<div class="method-example">
|
||||
<code class="method-declaration">
|
||||
GET https://DomainName/api/v1/templates/template
|
||||
</code>
|
||||
<code class="method-response">
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Test",
|
||||
"entity": "loan",
|
||||
"type": "Document",
|
||||
"text": "This is a loan for {{loan.clientName}}",
|
||||
"mappers": [
|
||||
{
|
||||
"mapperorder": 0,
|
||||
"mapperkey": "loan",
|
||||
"mappervalue": "loans/{{loanId}}?associations=all&tenantIdentifier={{tenantIdentifier}}",
|
||||
"id": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
</code>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<a id="resources_addtemplate" name="resources_addtemplate"
|
||||
class="old-syle-anchor"> </a>
|
||||
<div class="method-section">
|
||||
<div class="method-description">
|
||||
<h4>Add a Template</h4>
|
||||
<p>Adds a new template.</p>
|
||||
<table class=matrixHeading>
|
||||
<tr class="matrixHeadingBG">
|
||||
<td><div class="mifosXHeading2">Mandatory Fields</div></td>
|
||||
</tr>
|
||||
<tr class=alt>
|
||||
<td>name</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p>Example Requests:</p>
|
||||
<div class=apiClick>templates/1</div>
|
||||
</div>
|
||||
<div class="method-example">
|
||||
<code class="method-declaration">
|
||||
POST https://DomainName/api/v1/templates
|
||||
</code>
|
||||
<code class="method-request">
|
||||
POST templates
|
||||
Content-Type: application/json
|
||||
Request Body:
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Test",
|
||||
"entity": "loan",
|
||||
"type": "Document",
|
||||
"text": "This is a loan for {{loan.clientName}}",
|
||||
"mappers": [
|
||||
{
|
||||
"mapperorder": 0,
|
||||
"mapperkey": "loan",
|
||||
"mappervalue": "loans/{{loanId}}?associations=all&tenantIdentifier={{tenantIdentifier}}",
|
||||
"id": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
</code>
|
||||
<code class="method-response">
|
||||
{
|
||||
"resourceId": 1
|
||||
}
|
||||
</code>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<a id="resource_templatelist" name="resource_templatelist"
|
||||
class="old-syle-anchor"> </a>
|
||||
<div class="method-section">
|
||||
<div class="method-description">
|
||||
<h4>Retrieve all Templates</h4>
|
||||
|
||||
<p>Example Requests:</p>
|
||||
<div class=apiClick>templates</div>
|
||||
<br>
|
||||
<p>
|
||||
It is also possible to get specific templates by entity and type:
|
||||
</p>
|
||||
<div class=apiClick>templates?type=0&entity=0</div>
|
||||
<br>
|
||||
<table class=matrixHeading>
|
||||
<tr class="matrixHeadingBG">
|
||||
<td><div class="mifosXHeading2">Entity</div></td>
|
||||
<td>Id</td>
|
||||
<td><div class="mifosXHeading2">Type</div></td>
|
||||
<td>Id</td>
|
||||
</tr>
|
||||
<tr class=alt>
|
||||
<td>client</td>
|
||||
<td>0</td>
|
||||
<td>Document</td>
|
||||
<td>0</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>loan</td>
|
||||
<td>1</td>
|
||||
<td>E-Mail (not yet)</td>
|
||||
<td>1</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td></td>
|
||||
<td></td>
|
||||
<td>SMS (not yet)</td>
|
||||
<td>2</td>
|
||||
</tr>
|
||||
</table>
|
||||
</div>
|
||||
<div class="method-example">
|
||||
<code class="method-declaration">
|
||||
GET https://DomainName/api/v1/templates
|
||||
</code>
|
||||
<code class="method-response">
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Test",
|
||||
"entity": "loan",
|
||||
"type": "Document",
|
||||
"text": "This is a loan for {{loan.clientName}}",
|
||||
"mappers": [
|
||||
{
|
||||
"mapperorder": 0,
|
||||
"mapperkey": "loan",
|
||||
"mappervalue": "loans/{{loanId}}?associations=all&tenantIdentifier={{tenantIdentifier}}",
|
||||
"id": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
</code>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<a id="resources_retrievetemplate" name="resources_retrievetemplate"
|
||||
class="old-syle-anchor"> </a>
|
||||
<div class="method-section">
|
||||
<div class="method-description">
|
||||
<h4>Retrieve a Template</h4>
|
||||
<p>Example Requests:</p>
|
||||
<div class=apiClick>templates/1</div>
|
||||
</div>
|
||||
<div class="method-example">
|
||||
<code class="method-declaration">
|
||||
GET https://DomainName/api/v1/templates/{Id}
|
||||
</code>
|
||||
<code class="method-response">
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Test",
|
||||
"entity": "loan",
|
||||
"type": "Document",
|
||||
"text": "This is a loan for {{loan.clientName}}",
|
||||
"mappers": [
|
||||
{
|
||||
"mapperorder": 0,
|
||||
"mapperkey": "loan",
|
||||
"mappervalue": "loans/{{loanId}}?associations=all&tenantIdentifier={{tenantIdentifier}}",
|
||||
"id": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
</code>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<a id="resources_updatetemplate" name="resources_updatetemplate"
|
||||
class="old-syle-anchor"> </a>
|
||||
<div class="method-section">
|
||||
<div class="method-description">
|
||||
<h4>Update a Template</h4>
|
||||
</div>
|
||||
<div class="method-example">
|
||||
<code class="method-declaration">
|
||||
PUT https://DomainName/api/v1/templates/{templateId}
|
||||
</code>
|
||||
<code class="method-request">
|
||||
PUT templates/1
|
||||
Content-Type: application/json
|
||||
Request Body:
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Test",
|
||||
"entity": "loan",
|
||||
"type": "Document",
|
||||
"text": "This is a loan for {{loan.clientName}}",
|
||||
"mappers": [
|
||||
{
|
||||
"mapperorder": 0,
|
||||
"mapperkey": "loan",
|
||||
"mappervalue": "loans/{{loanId}}?associations=all&tenantIdentifier={{tenantIdentifier}}",
|
||||
"id": 1
|
||||
}
|
||||
]
|
||||
}
|
||||
</code>
|
||||
<code class="method-response">
|
||||
{
|
||||
"resourceId": 1
|
||||
}
|
||||
</code>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<a id="resources_deletetemplate" name="resources_deletetemplate"
|
||||
class="old-syle-anchor"> </a>
|
||||
<div class="method-section">
|
||||
<div class="method-description">
|
||||
<h4>Delete a Template</h4>
|
||||
</div>
|
||||
<div class="method-example">
|
||||
<code class="method-declaration">
|
||||
DELETE https://DomainName/api/v1/templates/{templateId}
|
||||
</code>
|
||||
<code class="method-request">
|
||||
DELETE templates/1
|
||||
Content-Type: application/json
|
||||
No Request Body:
|
||||
</code>
|
||||
<code class="method-response">
|
||||
{
|
||||
"resourceId": 1
|
||||
}
|
||||
</code>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- end of template api docs -->
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
<!-- main-content-wrapper -->
|
||||
|
||||
|
||||
Reference in New Issue
Block a user