Resource Staging

Resource staging is the mechanism through which Indicium controls the state of a record or a set of parameters while it is being edited by a user. Every insert, update, task and report action is represented by a staged resource. Every change made by a user in a GUI is performed by a request to Indicium's API to change the state of the resource. Every change that is made to a resource by means of application logic, however, is done automatically by Indicium whenever necessary (see also this blog on resource staging).

The process of resource staging consists of a number of predefined steps that can be called by multiple separate requests or by one single request, depending on the specific needs and preferences of the application that is calling Indicium.

• When Indicium is called automatically by some third party application or service or by an application that contains no application logic, single request resource staging may be preferred.
• On the other hand, when Indicium is called by a graphical user interface and the feedback of a call may be shown to end users, it may be preferred to use multiple requests for resource staging.

On this page, both the single request and the multiple separate requests (consisting of the following steps: creating a resource, optionally patching a value to the resource and committing the resource) are explained by a description of all the available endpoints and all the available operations on each endpoint, including supported operation parameters and navigation properties.

1. Creating a resource

A new resource can be created by simply sending a POST request without a body to the target entity's endpoint, followed by:

• /stage_add to stage a new row.
• /stage_edit to stage a row to be edited.
• /stage_copy to stage a copy of a row.
• /stage to stage a task or report.

Keep in mind that /stage_add assumes an entity set without a key filter (e.g. /country), while /stage_edit and /stage_copy both assume an individual entity or active row (e.g. /country(#), which is a record of the entity country). Tasks and reports can be staged outside the context of a table.

If the request is successful, Indicium will respond with a HTTP status code 201 and a Location header that points to the newly created resource.

Request examples

Request	Method	Url	Response	Location header
Add a new record	POST	/iam/appl/country/stage_add	201 Created	iam/appl/staged_country(#)
Edit a record	POST	/iam/appl/country(#)/stage_edit	201 Created	iam/appl/staged_country(#)
Copy a record	POST	/iam/appl/country(#)/stage_copy	201 Created	iam/appl/staged_country(#)
Stage a task	POST	/iam/appl/delete_country/stage	201 Created	iam/appl/staged_delete_country(#)
Stage a report	POST	/iam/appl/preview_country/stage	201 Created	iam/appl/staged_preview_country(#)

1.1 Context filter propagation

When a row, task or report is staged, possible default values, expressions, and application logic are calculated and applied automatically by Indicium. Furthermore, in the case of an inter-entity relationship, any available context values are propagated to the resource. Inter-entity relations exist when a table column establishes a link from the table it resides in, to a table column in another, related table. In resource staging, these reference columns are used to propagate context values to the resource.

For example, a Province table is linked to a Country table in a master-detail relation (through the use of Country's primary key country_id). Now a new Province row can be staged in context of a specific Country. This means that country_id is used as a context filter for the new Province row, causing the Country of the new row to default to the specific Country that is provided. So country_id filters the data of Province on its Country context and values of this context are propagated to the resource.

Multiple context filters

Context filter propagation can be achieved using multiple context filters. Furthermore, context filters will always be applied, even when there is no active row.

Suppose City is a detail of Province and Province on its turn is linked in detail to Country. When a new City row is staged using both country_id and province_id as context filters, both context filters will be applied on the newly created City resource. So both Country and Province values will default to the given values.

Now, consider the situation that a Country record exists, but there is no Province record. In this case, a new City row can still be staged in context of a specific Country, but only country_id will be applied to the resource.

note

See the request examples in navigation properties for some examples of how such requests look like.

Look-ups, reports and tasks

Context filters are not only propagated to details, but also to look-ups, and to tasks and reports. And here also applies that context values will be propagated even when there is no active row.

Take the situation outlined above: only a Country record exists, no Province or City record. Now, it's not only possible to stage a new City row in context of the existing country, but also to open the look-up back to Province and stage a new Province row through the look-up from City with country_id as a context filter for this new Province.

In the case of tasks and reports, context filters are propagated via table task and table report parameters.

For example, the report preview_country is linked to the Country table, through a report parameter that is mapped to the country_id column. A new report can be staged in context of a specific Country, so the report parameter will default to the given Country. But suppose that the report is linked to the Province table and the report parameter is mapped to the country_id column. Then, when there is no Province record, only a Country record, and a report is staged in context of this Country, an empty Province row will be created with the Country values propagated to it and this row will be used as a context filter for the report. So the report parameter will still default to the given Country, even when there is no active row in the direct 'parent' entity.

note

See the request examples in navigation properties for some examples of how such requests look like.

Context propagation on staged resources

The root context of an staging action does not always have to be an entity in the database, it can also be a staged entity. This makes it possible to, for example, stage a new row through a look-up that is opened from a staged report or task. Context propagation should even in these cases be applied.

note

See the request examples in navigation properties for an example of how such a request looks like.

1.2 Navigation properties

To propagate context to a resource, navigation properties are used. Navigation properties allow for navigation from one entity to the other related entity and, depending on the way you are navigating, there are different types of navigation properties available.

• To propagate context from master to detail, a one-to-many (entity to entity set) navigation property for details is available, prefixed with detail_.

• Navigation properties for look-ups are available prefixed with list_ or lookup_. The difference is:

  • list_ is a one-to-many navigation property, it refers to a lookup set.
  • lookup_ is a one-to-one navigation property, it refers to a single entity.

• To propagate context to tasks and reports, navigation properties for tasks (task_) and reports (report_) are available.

• To propagate context when there is no active row in between, a navigation property prefixed with empty_ is used.

• Furthermore, a translation navigation property is available, that connects the entity in question to the entity that contains the display value of the lookup. This one-to-one navigation property is prefixed with transl_ and can be used to select the display value of the lookup or filter on it when retrieving a staged resource.

The metadocument of an application ($metadata) lists the specific navigation properties that are available for the entities in that application.

Navigation property	Prefix	Example
Propagate context to detail	detail_	/detail_ref_country_province
Propagate context to lookup (one-to-one)	lookup_	/lookup_country_id
Propagate context to lookup (one-to-many)	list_	/list_country_id
Propagate context to task	task_	/task_delete_country
Propagate context to report	report_	/report_preview_country
Propagate context with empty set in between	empty_	/empty_detail_ref_country_province
Connect one entity to the other entity that contains the display value of the lookup	transl_	/transl_province_id

When creating a resource, the actions /stage_add and /stage (for tasks and reports) can be called on navigation properties to propagate context to the staged resource. Technically, /stage_copy can also be called. But because /stage_copy will always be called on an individual entity, context will never be propagated and using navigation properties will only make the request unnecessarily complex. For the same reason, /stage_edit cannot be called on navigation properties.

Request examples

Url	Result
/country(99)/detail_ref_country_province/stage_add	A new row will be staged in the province table, country_id must default to 99.
/province(country_id=99, province_id=1)/detail_ref_province_city/stage_add	A new row will be staged in the city table, country_id must default to 99 and province_id to 1.
/country(99)/empty_detail_ref_country_province/ detail_ref_province_city/stage_add	A new row will be staged in the city table, no province row is selected so only country_id will be applied to the resource.
/country(99)/empty_detail_ref_country_province/ empty_detail_ref_province_city/list_province_id/stage_add	A new row will be staged in the province table, through the province_id lookup that is opened from city with no active row. Country_id will be applied to the resource.
/country(99)/task_delete_country/stage	A task will be staged, the task parameter that is linked to country_id will default to the given country.
/country(99)/report_preview_country/stage	A report will be staged, the report parameter that is linked to country_id will default to the given country.
/country(99)/empty_detail_ref_country_province/ report_preview_country/stage	A report will be staged, the report parameter that is linked to country_id will default to the given country.
/staged_report_preview_country(1)/list_province_id/stage_add	A new row will be staged in the province table, through the province_id lookup that is opened from a staged report. The report is staged in context of a country, so country_id will be applied to the new Province row.

If the request is sent successfully, a new resource with a temporary key (#) will be created on which individual PATCH actions may be taken.

2. Patching a value to the resource

When a row, task or report is staged, one or more values may be added or updated to the resource. To modify a staged resource, submit a PATCH request to the staged resource's endpoint with a JSON request body that contains the column or parameter to be added or edited and the desired value as a key:value pair. The layout state, that is maintained by the staged resource itself, is used to check whether incoming PATCH actions are allowed, whether look-ups are filled with valid values and whether input values comply with data type restrictions (e.g. min/max values, length or domain elements).

note

Keep in mind that in order to have the application logic work properly, Indicium needs to know the order in which individual columns are edited. Therefore, the request body should contain exactly one property. This means that multiple PATCH requests are needed whenever more than one value needs to be added or updated.

If the request is successful, Indicium will respond with a HTTP status code 200 and a JSON response body containing indicators whether the the resource or its layout state has been updated and whether one or more properties have been cleared.

• The indicator layout_changed will be true when in the SF is specified that a change to the specific table or table column can trigger the layout procedure (this can be specified in the Subjects Performance tab in the SF).
• The indicator resource_changed will be true if, apart from the patched column or parameter, more columns/parameters have been updated in the resource (e.g. by a default procedure or expression).
• In the situation that one property acts as a lookup filter for other properties, these underlying properties should be emptied when the lookup filter property is changed. In that case the indicator clear_cache is also returned, which indicates which properties have been emptied.

Request example

Request	Method	Url	JSON request body	Response
Update a staged resource	PATCH	iam/appl/staged_country(#)	{"name": "Netherlands"}	200 OK

JSON response body example

{
    "@odata.context": "http://localhost/iam/appl/$metadata#APPLICATION.complex",
    "layout_changed": true,
    "resource_changed": true,
    "clear_cache@odata.type": "#Collection(String)",
    "clear_cache": [
        "province_id"
    ]
}

3. Committing a resource

After staging a resource and possibly patching a value to the resource, a commit action is needed to actually save or update the row (when adding, editing or copying a record), execute the task or export the report. A resource can be committed by sending a POST request without a body to the staged resource's endpoint, followed by /commit.

If the request is successful, the staged resource will be destroyed and depending on the resource that is staged, Indicium will return a different response. If the staged resource references a row, Indicium will respond with a HTTP status code 201 and a Location header that points to the newly created or updated record. Does the staged resource reference a task, then Indicium will respond with a HTTP status code 204 and the task will be executed. In this case, the Location header and response body will be empty. If a staged report is committed, Indicium will respond with a HTTP status code 200 together with the binary stream of the exported report in the response body.

You can automatically download a report when committing a resource. To enable this, append ?direct_download=true to the url. The report will be returned immediately on /commit.

Request examples

Request	Method	Url	Response	Location header	Response body
Save or update row	POST	iam/appl/staged_country(#)/commit	201 Created	iam/appl/country(#)	-
Execute task	POST	iam/appl/staged_task_delete_country(#) /commit	204 No Content	-	-
Execute report	POST	iam/appl/staged_report_preview_country(#) /commit	200 OK	-	Binary stream

4. Retrieving or deleting a resource

During the whole process of resource staging, the staged resource or its layout state can be accessed by submitting a GET request. A GET request on the staged resource can be combined with one or more parameters and navigation properties to filter, sort or expand the results.

If a request is successful, Indicium will respond with a HTTP status code 200 and the requested content will be returned in the JSON response body.

Request examples

Method	Parameter/navigation property	Url	Result
GET	-	/staged_province(#)	The staged resource will be returned with all known province values
GET	-	/staged_province(#)/layout()	The layout state of the staged resource will be returned
GET	$expand and transl_	/staged_province(#)?$expand =transl_country_id	All known province values will be returned expanded with the values of the referenced country
GET	$expand, transl_ and $select	/staged_province(#)?$expand<br />=transl_country_id($select=name)	All known province values will be returned expanded with only the name value of the referenced country
GET	lookup_ and detail_	/staged_province(#)/lookup_country_id/ detail_ref_country_province	All 'sisters' will be returned: the provinces that are connected to the country that is referenced by the staged province

JSON response body examples

GET 
/staged_province(#)

{
    "@odata.context": "http://localhost/iam/appl/$metadata#staged_province/$entity",
    "staged_resource_id": 1,
    "country_id": 1,
    "province_id": 1,
    "name": "Province1"
}

GET 
/staged_province(#)?$expand=transl_country_id

{
    "@odata.context": "http://localhost/iam/appl/$metadata#staged_province/$entity",
    "staged_resource_id": 1,
    "province_id": 1,
    "name": "Province1",
    "transl_country_id": {
        "country_id": 1,
        "name": "Country1",
        "eu_member": true
    }
}

GET 
/staged_province(#)?$expand=transl_country_id($select=name)

{
    "@odata.context": "http://localhost/iam/appl/$metadata#staged_province/$entity",
    "staged_resource_id": 1,
    "province_id": 1,
    "name": "Province1",
    "transl_country_id": {
        "name": "Country1"
    }
}

GET 
/staged_province(#)/lookup_country_id/detail_ref_country_province

{
    "@odata.context": "http://localhost/iam/appl/$metadata#province",
    "value": [
        {
            "country_id": 1,
            "province_id": 1,
            "name": "Province1"
        },
        {
            "country_id": 1,
            "province_id": 2,
            "name": "Province2"
        }
    ]
}

A DELETE request on the staged resource will cancel the editing and destroy the resource (not the actual record!). If successful, Indicium will respond with a HTTP status code 204.

Request	Method	Url	Response
Cancel editing	DELETE	/iam/appl/staged_country(#)	204 No Content

5. Single request resource staging

When using resource staging as described above, at least three (and possibly more) separate requests are needed to create a resource, patch values to it and eventually commit the resource. To simplify this process, Indicium has re-enabled the single request APIs so clients can send all column values in a single request.

Resource staging with a single request can be particularly handy in situations that application logic needs to be handled, but there is no user interface that needs to be updated depending on this logic. For example, when Indicium is called automatically by a third party application or service or by some scheduled process. In these cases, when there is no need to indicate to some user whether or not input fields are mandatory, disabled etcetera, a record can still be saved in a single request.

To add a record, execute a task or export a report in a single request, simply send a POST request with all desired column values in the JSON request body to the target entity's endpoint. To update a record, send a PATCH request instead of a POST. Indicium will still go through the whole process of resource staging and stage the values in the order that they're supplied in. This does mean that the order of the properties in the request body is important.

Keep in mind that, just like when using multiple requests for resource staging, with a single request it is also possible to propagate context to a detail, look-up, task or report using navigation properties (see navigation properties for some request examples).

Indicium responds:

• If a record is successfully added or updated, Indicium will respond with a HTTP status code 201 and a Location header that points to the newly created or updated record.
• If a task is successfully executed, Indicium will just respond with a HTTP status code 204, the Location header and response body will be empty.
• If a report is exported, Indicium will respond with a HTTP status code 200 together with the binary stream of the exported report in the response body.

Request examples

Request	Method	Url	JSON request body	Response	Location header	Response body
Add a new record	POST	iam/appl/ country	{"name": "Netherlands","eu_member": true}	201 Created	iam/appl/country(#)	-
Edit a record	PATCH	iam/appl/ country(#)	{"eu_member": false}	201 Created	iam/appl/country(#)	-
Execute a task	POST	iam/appl/ delete_country	{"name": "Netherlands"}	204 No Content	-	-
Export a report	POST	iam/appl/ preview_country	{"name": "Netherlands"}	200 OK	-	Binary stream

6. Include layout and include resource

When staging or patching a resource, it is common to do a GET on the staged resource to retrieve the current state of the staged resource and do a /Layout() call.

To include the response of the GET and /layout() calls in the response of your stage or PATCH call, you can use two query string parameters; include_resource and include_layout. These parameters can be powerful to speed up the process of staging and patching and simultaneously reduce the number of calls to Indicium. This could reduce the load of Indicium on the server(s).

• Add include_resource with a true value to the query string to add the Resource property to the result.
• Add include_layout with a true value to add the Layout property to the result.

Note: that include_resource will only add the resource to the response if it has changed from the perspective of the client. For example, if a PATCH call causes the default procedure to change a value or an expression to change, then include_resource will cause the resource to be included in the reponse.

Both parameters are boolean types, so they can only contain a true or a false value; their default value is false. You can use the parameters in the following methods:

• Stage_add
• Stage_edit
• Stage_copy
• Stage_task
• Stage_report
• Patch
• Choose

Example

GET 
/iam/appl/country/stage_add?include_layout=true&include_resource=true

{
    "@odata.context": "http://localhost/iam/appl/$metadata#appl.complex",
    "resource": {
        "@odata.type": "#appl.country",
        "name": "The Netherlands"
    },
    "layout": {
        "@odata.type": "#appl.complex",
        "add_button_type": 0,
        "update_button_type": 0,
        "delete_button_type": 0,
        "confirm_button_type": 0,
        "cancel_button_type": 0,
        "name_type@odata.type": "#Byte",
        "name_type": 0,
        "name_mand@odata.type": "#Byte",
        "name_mand": 1,
    }
}