Module Web Service

MpRIA supports a REST oriented web service API using the HTTP Protocol and its methods GET, POST, PUT and DELETE. The message body has an XML format defined by XML schema. The API provides CRUD operations. The only supported content type is application/xml. Make sure to include the following HTTP header when sending a message body:

Content Type: application/xml

Security and authentication

Encryption

The API provides access to all kinds of data including personal data like addresses. Therefore the data transmission is always encrypted. The encryption is realized via HTTPS (SSL) certificate encrypted transmission.

HTTP Basic authentication

HTTP basic authentication is used for user authentication. As a colon : is used to separate the username from the password, it prevents using usernames containing a colon. This limitation does not exist for the password. See IETF’s RFC 2617 for more details about HTTP basic authentication.

The orgUnit infrastructure that is used to handle user permissions in the MpRIA Frontend is also used for the web service API. That means that web service API users will also be able to login to the graphical user interface. All access limitations provided by the orgUnits will be equally valid for web service and the graphical user interface.

Two-factor authentication is also supported. When enabled a security token (sent by email or cellphone) must be provided in addition to the username and password.

Any request with invalid credentials will be rejected with HTTP status code 403 (Forbidden).

User session service

The HTTP Basic authentication mechanism is recommended for simplicity. You can safely skip this session if you don’t plan to use two-factor authentication.

The session service is used to explicitly request a session key that can be reused in multiple API calls. The session service use is only mandatory if the configuration has two factor authentication enabled. If not the username and password can also be given directly in the HTTP Authorization header. This implicitly creates a one request user session.

One important remark is that the user session that is meant here is not to be confused with an HTTP session. Whenever we talk about a session in the context of this service, a user session and not an HTTP session is meant.

When first requesting a session key the user has to authenticate himself via HTTP basic authentication with username and password. While the username is given in clear text, the password field has an enhanced syntax to solve our requirements for multiple authentication stages.

The first session request uses the username and password in the following form. The example assumes a user named martin and a password abcd1234. The username and password are wrapped in square brackets with an identifier prefix.

user[martin]:password[abcd1234]

When two factor authentication is enabled, the above request sends a security token to the users email or cellphone. In this case, a pending session key is returned. The pending session has to be activated with a security token. If the user tries to authenticate with the password again, a new security token is generated and send to the user. The pending session will timeout. To authenticate with a security token, the token identifier is used with the security token in square brackets. If the security token is valid, the session key will be returned without the pending attribute.

session[jalsd7ajsd7764asbh1hnad9871nd89h]:token[3621]

All other requests to the services have to use a valid session key. The authentication header has to have the following form.

user[martin]:session[jalsd7ajsd7764asbh1hnad9871nd89h]

There exists a session timeout. The timeout depends on the solution. With every request the timeout will be reset.

User session API methods

Request a session key.
GET http://.../ria-ws/application/session

response body definition: session_1_0.xsd

response body example: session.xml

HTTP authentication header has to be filled as described above. If the credentials are valid, HTTP status code 200 (OK) is returned. The response contains a message of a format defined in session_1_0.xsd. If two factor authentication is enabled. A session key for a pending session will be returned. The session has to be activated with a valid security token.

Delete / invalidate a session
DELETE http://.../ria-ws/application/session/{session-key}

Delete respectively invalidate a session with the given session-key. A session can only be closed by the user that owns the session or by timeout. The user has to have valid credentials including user and session. The method returns HTTP status code 200 (OK) if the session was deleted.

Module Service

The module service provides CRUD operations for MpRIA modules. The definition of the available modules depends on the solution and can be retrieved via the data definition method (see below).

It is highly recommended to call the data definition method /ria-ws/application/module/definition first and manually inspect the output in order to retrieve the list of available modules and field that can be used with the web services.

Terminology

MpRIA is a highly configurable application framework that can be tailored to build standard or custom applications. As a result the API is very generic (as it doesn’t know the specific data structures used by the applications). A knowledge of the MpRIA framework as well as the specifics of the application (modules, field names, etc.) is needed to be able to use the API. To know which fields are available on each module, use the data definition method /ria-ws/application/module/definition.

  • Module: A module contains the definition of fields and screens for given business needs. Example modules are: objects, addresses, exhibitions, movement, multimedia, etc. The modules are presented in the top ribbon in the MpRIA frontend. This would be similar to the list of tables in an SQL database system.

  • Field (or attributes): Each module has a list of fields that can be filled when creating an item for the module. For example on the Object module, there may be an "object number" field as well as an "object description". Field names follow a naming convention: They are prefixed with the module name (e.g. Obj) and suffixed with the field type (e.g Txt for a text field, Lnu for a long numeric field, etc.). As a result the "object number" field would be named ObjObjectNumberLnu and the description ObjObjectDescriptionTxt. This would be similar to the columns definition of a table in an SQL database.

  • Item (or record): While the module defines the data structure, an item is an actual instance of a module created by a user. For example there may be an Object module, and one of its items could be "The Starry Night" painting by Vincent Van Gogh. This would be similar to a row in an SQL database.

  • Reference: In addition to value fields, MpRIA supports reference fields to link module items together. For example a painting from the Object module may have a reference to the Address module to store its owner. References can be single-valued or multi-valued. This would be similar to a foreign key in a SQL database.

  • Repeatable group: A repeatable group is similar to a reference and allows to link multiple rows of data within a module item. For example an item from the Object module can have multiple alternate titles, in different languages. They would be stored in a repeatable group as they don’t reference another module, but are multi-valued. For API purposes repeatable groups can be considered identical to references in most cases (the same API methods are used for repeatable groups and references).

  • Vocabulary: For some value fields a fixed list of values can be configured, rather than free-form entry. The fixed list translates to a drop-down control in the front-end, and is comparable to an enumeration. This fixed list is called a Vocabulary in MpRIA. For example there may be an "Address type" vocabulary with the values "Private", "Professional". Vocabularies can be flat lists or complex hierarchical thesauruses. Each value of a vocabulary is called a "node". Nodes have logical names (their internal, technical names) and localized labels which are called "terms".

  • Attachment: Every module item has support to handle exactly one attachment, a multimedia file stored with the item. An attachment is usually an image, but can be any document type. When multiple attachments are needed they are handled by configuring a reference to the Multimedia module.

  • orgUnit: (Organisational Unit): All data items within MpRIA belong to an orgUnit. The orgUnit is tied to permissions and roles to define who has access to a module item, and which type of access (read, write, etc.).

Locale Specific Formatting

The message formats contain some locale specific formatting in the formattedValue elements. The user can submit a locale with the Accept-Language HTTP Header field. The system will try to use the desired locale. If the given locale is not available, a solution specific fallback is used.

API Methods

Create new module items

POST http://.../ria-ws/application/module/{module}
  • Parameters:

    • module: Module under which to create the items (e.g. "Object", "Address", etc.)

  • Request body definition: module_1_6.xsd

  • Response body definition: module_1_6.xsd

Create new module items. Adds module items including repeatable groups and references. The method returns a small response including the identifier of the newly created module item. Limitation on the size of the request may apply depending of the application container configuration.

Example

Add a new record in the Address module:

curl -X "POST" "https://<host>/<application>/ria-ws/application/module/Address/" \
	-u <Username>:<Password> \
	-H "Content-Type: application/xml" \
	-d $'<application xmlns="http://www.zetcom.com/ria/ws/module">
  <modules>
    <module name="Address">
      <moduleItem>
        <dataField name="AdrPostcodeTxt">
          <value>12345</value>
        </dataField>
        <dataField name="AdrSurNameTxt">
          <value>Muster</value>
        </dataField>
        <dataField name="AdrStreetTxt">
          <value>Köpenickerstr. 154</value>
        </dataField>
        <dataField name="AdrCityTxt">
          <value>Berlin</value>
        </dataField>
        <dataField name="AdrForeNameTxt">
          <value>Max</value>
        </dataField>
        <dataField name="AdrCountryTxt">
          <value>Germany</value>
        </dataField>
        <dataField dataType="Varchar" name="AdrCountyTxt">
          <value>Berlin</value>
        </dataField>
        <vocabularyReference name="AdrSendEmailVoc">
          <vocabularyReferenceItem id="30891" />
        </vocabularyReference>
        <vocabularyReference name="AdrSendPostVoc">
          <vocabularyReferenceItem id="30891" />
        </vocabularyReference>
        <repeatableGroup name="AdrContactGrp">
          <repeatableGroupItem>
            <dataField name="ValueTxt">
              <value>max.muster@gmail.com</value>
            </dataField>
            <vocabularyReference name="TypeVoc">
              <vocabularyReferenceItem id="30152" />
            </vocabularyReference>
          </repeatableGroupItem>
          <repeatableGroupItem>
            <dataField name="ValueTxt">
              <value>(555)555-5555</value>
            </dataField>
            <vocabularyReference name="TypeVoc">
              <vocabularyReferenceItem id="30150" />
            </vocabularyReference>
          </repeatableGroupItem>
        </repeatableGroup>
        <moduleReference name="AdrAddressGroupRef">
          <moduleReferenceItem moduleItemId="12011" />
        </moduleReference>
      </moduleItem>
    </module>
  </modules>
</application>'

Create repeatable group / reference

POST http://.../ria-ws/application/module/{module}/{__id}/{repeatableGroup|reference}
  • Parameters:

    • module: Name of the module for the parent object containing the group / reference

    • _id: Parent module item ID to add the group / reference to

    • repeatableGroup|reference: Name of the reference field or repeatable group in the parent module to add the group / reference to

  • Request body definition: module_1_6.xsd

Create a new repeatable group or reference and add it to the module item specified by the {__id}

Example

Add a repeatable group item of type AdrContactGrp to an Address with ID 29011:
curl -X "POST" "https://<host>/<application>/ria-ws/application/module/Address/29011/AdrContactGrp" \
	-u <Username>:<Password> \
	-H "Content-Type: application/xml" \
	-d $'<application xmlns="http://www.zetcom.com/ria/ws/module">
  <modules>
    <module name="Address">
      <moduleItem id="29011">
        <repeatableGroup name="AdrContactGrp">
          <repeatableGroupItem>
            <dataField name="ValueTxt">
              <value>max_muster</value>
            </dataField>
            <vocabularyReference name="TypeVoc">
              <vocabularyReferenceItem id="30158" />
            </vocabularyReference>
          </repeatableGroupItem>
        </repeatableGroup>
      </moduleItem>
    </module>
  </modules>
</application>'

Add a reference to a reference field within a repeatable group

POST http://.../ria-ws/application/module/{module}/{__id}/{repeatableGroup}/{__groupId}/{reference}
  • Parameters:

    • module: Name of the module for the parent object containing the group

    • _id: Parent module item ID containing the group

    • repeatableGroup: Name of the group containing the reference field to add the reference to

    • __groupId: ID of the group item that should contain the new reference

    • reference: Name of the reference field within the group where the reference should be added

  • Request body definition: module_1_6.xsd

Add references to a given repeatable group.

Perform an ad-hoc search for modules items

POST http://.../ria-ws/application/module/{module}/search/

The search service provides a way to send a module search expression in the form of an xml message body.

Example

Shows an search on the Address module using different filter criteria:

curl -X "POST" "https://<host>/<application>/ria-ws/application/module/Address/search" \
	-u <Username>:<Password> \
	-H "Content-Type: application/xml" \
	-d $'<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://www.zetcom.com/ria/ws/module/search" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zetcom.com/ria/ws/module/search http://www.zetcom.com/ria/ws/module/search/search_1_1.xsd">
  <modules>
  <module name="Address">
    <search limit="10" offset="0">
      <expert>
        <and>
          <equalsField fieldPath="AdrCountryTxt" operand="Germany" />
          <isNotBlank fieldPath="AdrContactGrp.ValueTxt" />
          <equalsField fieldPath="AdrContactGrp.TypeVoc" operand="30150"/>
        </and>
      </expert>
    </search>
  </module>
</modules>
</application>'

Search for all Addresses and select only chosen fields of each returned Address. Selecting fields makes sense cause it limits bandwidth and increases performance especially when references are not needed.

curl -X "POST" "https://<host>/<application>/ria-ws/application/module/Address/search" \
	-u <Username>:<Password> \
	-H "Content-Type: application/xml" \
	-d $'<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://www.zetcom.com/ria/ws/module/search" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zetcom.com/ria/ws/module/search http://www.zetcom.com/ria/ws/module/search/search_1_1.xsd">
  <modules>
    <module name="Address">
      <search limit="10" offset="0">
        <select>
     	  <field fieldPath="__id"/>
          <field fieldPath="AdrSurNameTxt"/>
          <field fieldPath="AdrForeNameTxt"/>
          <field fieldPath="AdrContactGrp"/>
          <field fieldPath="AdrContactGrp.repeatableGroupItem"/>
          <field fieldPath="AdrContactGrp.ValueTxt"/>
          <field fieldPath="AdrContactGrp.TypeVoc"/>
          <field fieldPath="AdrAddressGroupRef"/>
          <field fieldPath="AdrAddressGroupRef.moduleReferenceItem" />
          <field fieldPath="AdrAddressGroupRef.formattedValue"/>
        </select>
        <fulltext>*</fulltext>
      </search>
    </module>
  </modules>
</application>'

Note that by default repeatable groups are summarized only with the size and module references only with the size, target module and multiplicity. If more or all details from repeatable group items or module reference records should be present in the response, too, an explicit keyword has to be added to the selection. For repeatable groups this keyword is {repeatableGroup}.repeatableGroupItem. For module references this keyword is {reference}.moduleReferenceItem.

These keywords have already been used above:

    ...
        <select>
            ...
            <field fieldPath="AdrContactGrp"/>
            <field fieldPath="AdrContactGrp.repeatableGroupItem"/>
            ...
            <field fieldPath="AdrAddressGroupRef"/>
            <field fieldPath="AdrAddressGroupRef.moduleReferenceItem" />
        </select>
    ...

Search for all addresses that were modified in a specified range.

curl -X "POST" "https://localhost:8181/MpWeb-dev/ria-ws/application/module/Address/search" \
     -H 'Content-Type: application/xml' \
     -u '<Username>:<Password>' \
     -d $'<application xmlns="http://www.zetcom.com/ria/ws/module/search" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zetcom.com/ria/ws/module/search http://www.zetcom.com/ria/ws/module/search/search_1_4.xsd">
    <modules>
      <module name="Address">
        <search limit="10" offset="0">
          <select>
            <field fieldPath="__id"/>
            <field fieldPath="__lastModified" />
            <field fieldPath="AdrSurNameTxt"/>
            <field fieldPath="AdrForeNameTxt"/>
            <field fieldPath="AdrContactGrp"/>
            <field fieldPath="AdrContactGrp.repeatableGroupItem"/>
            <field fieldPath="AdrContactGrp.ValueTxt"/>
            <field fieldPath="AdrContactGrp.TypeVoc"/>
            <field fieldPath="AdrAddressGroupRef"/>
            <field fieldPath="AdrAddressGroupRef.moduleReferenceItem" />
            <field fieldPath="AdrAddressGroupRef.formattedValue"/>
          </select>
          <expert>
            <betweenIncl fieldPath="__lastModified" operand1="2019-01-01T00:00:00Z" operand2="2019-09-01T00:00:00Z" />
          </expert>
        </search>
      </module>
    </modules>
  </application>'
POST http://.../ria-ws/application/module/{module}/search/savedQuery/{__id}
  • Parameters:

    • module: Name of the module to search items for

    • __id: Id of the saved search to run

  • Request body definition: search_1_7.xsd

  • Response body definition: module_1_6.xsd

  • Example request body: search.xml

  • Example response body: module.xml

Search with a saved query with __id. The __id of saved search queries can be retrieved with a search request in the search module.

A request body must be provided, in order to control the paging. For example:

  <application xmlns="http://www.zetcom.com/ria/ws/module/search" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zetcom.com/ria/ws/module/search http://www.zetcom.com/ria/ws/module/search/search_1_4.xsd">
    <modules>
      <module name="Object">
        <search limit="10" offset="0" />
      </module>
    </modules>
  </application>

The request body element <select> can be used for a projection and the offset and limit parameters work as expected. Currently this request does not support to extend the saved query with the given request body elements <fulltext>, <expert> and <sort>.

Use <sort> to sort the result of a search query

<application xmlns="http://www.zetcom.com/ria/ws/module/search" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://www.zetcom.com/ria/ws/module/search http://www.zetcom.com/ria/ws/module/search/search_1_7.xsd">
  <modules>
    <module name="Artist">
      <search>
        <select>
          <field fieldPath="__id"/>
          <field fieldPath="__lastModified"/>
        </select>
        <sort>
          <field fieldPath="__lastModified" direction="Descending"/>
        </sort>
      </search>
    </module>
  </modules>
</application>

Get a list of available exports / reports for a module

GET http://.../ria-ws/application/module/{module}/export
  • Parameters:

    • module: Name of the module to get the exports for

  • Request header:

    • Accept: application/xml or application/json

  • Response header:

    • Content-Type: application/xml or application/json

  • Response body definition: export_1_0.xsd

The export method provides a way to access the report mechanism. Returns a list of all available exports for the module. The request will return status code 200 (OK) if the request was correct and there is at least one export available. If there is no export for the module status code 204 (No Content) will be returned.

Example

List all available exports for module Address

curl -X "GET" "https://<host>/<application>/ria-ws/application/module/Address/export" \
	-u <Username>:<Password>

Export a single module item via the reporting system

GET http://.../ria-ws/application/module/{module}/{__id}/export/{id}
  • Parameters:

    • module: Name of the module to trigger the export for

    • __id: ID of the module item to export

    • id: ID of the export type / format, retrieved via the API method above

  • Request header:

    • Accept: application/octet-stream

  • Response header:

    • Content-Type: application/octet-stream

    • Content-Disposition: attachment;filename={random-file-name}.{export-specific-file-extension}

  • Response body definition: file as MIME type application/octet-stream

The export method provides a way to access the report mechanism. The specified module item {__id} will be exported in the specified format {id} The request will return status code 200 (OK) if the syntax of the request was correct. The content will be send using the MIME type application/octet-stream and the Content-disposition header with a suggested filename.

Example

Get an export of the Address record with ID 29011, with the format defined by the export type 4007. curl -O -J writes the resulting document to disk.

curl -O -J -X "GET" "https://<host>/<application>/ria-ws/application/module/Address/29011/export/4007" \
  -u <Username>:<Password>

Export multiple module items via the reporting system

POST http://.../ria-ws/application/module/{module}/export/{id}
  • Parameters:

    • module: Name of the module to trigger the export for

    • id: ID of the export type / format, retrieved via the API method above

  • Request header:

    • Accept: application/octet-stream

  • Request body definition: search_1_7.xsd

  • Response header:

    • Content-Type: application/octet-stream

    • Content-Disposition: attachment;filename={random-file-name}.{export-specific-file-extension}

  • Response body definition: file as MIME type application/octet-stream

The export method provides a way to access the report mechanism. The request body has to include a search expression. The search result will then be exported in the format specified by {id}. The request will return status code 200 (OK) if the syntax of the request was correct. The content will be send using the MIME type application/octet-stream and the Content-disposition header with a suggested filename.

Example

Searches for Addresses and downloads them using the export type / format 4007

curl -O -J -X "POST" "https://<host>/<application>/ria-ws/application/module/Address/export/4007" \
	-u <Username>:<Password> \
	-H "Content-Type: application/xml" \
	-d $'<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://www.zetcom.com/ria/ws/module/search" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zetcom.com/ria/ws/module/search http://www.zetcom.com/ria/ws/module/search/search_1_1.xsd">
  <modules>
    <module name="Address">
      <search limit="10" offset="0">
        <expert>
          <and>
            <equalsField fieldPath="AdrCountryTxt" operand="Germany" />
            <isNotBlank fieldPath="AdrContactGrp.ValueTxt" />
            <equalsField fieldPath="AdrContactGrp.TypeVoc" operand="30150"/>
          </and>
        </expert>
      </search>
    </module>
  </modules>
</application>'

Retrieve the data definition of all modules

GET http://.../ria-ws/application/module/definition/

Retrieves the definition of all modules. The message describes the modules with the same message format that is used for data retrieval and data changes. The difference is that the message contains all fields to define the structure of the modules without data.

Example

The following request returns an xml file including the full definition of all domain modules included in the application.

curl -X "GET" "https://<host>/<application>/ria-ws/application/module/definition" \
  -u <Username>:<Password>

Retrieve the data definition of a single module

GET http://.../ria-ws/application/module/{module}/definition/
  • Parameters:

    • module: Name of the module to get the data definition for

  • Response body definition: module_1_6.xsd

    Retrieves the definition of a given module. The message describes a module with the same message format that is
    used for data retrieval and data changes. The difference is that the message contains all fields to define the
    structure of the module without data.

Example

This request returns the definition of the Address module:

curl -X "GET" "https://<host>/<application>/ria-ws/application/module/Address/definition" \
	-u <Username>:<Password>

This request returns the definition of the AddressGroup module:

curl -X "GET" "https://<host>/<application>/ria-ws/application/module/AddressGroup/definition" \
	-u <Username>:<Password>

Get a single module item

GET http://.../ria-ws/application/module/{module}/{__id}
  • Parameters:

    • module: Name of the module to get the item from

    • __id: ID of the module item to retrieve

  • Response body definition: module_1_6.xsd

  • URL parameters (e.g. &loadAttachment=true):

    • loadAttachment | type: boolean | default: false | load attachment if exists

    • loadThumbnailExtraSmall | type: boolean | default: false | load extra small thumbnail

    • loadThumbnailSmall | type: boolean | default: false | load small thumbnail

    • loadThumbnailMedium | type: boolean | default: false | load medium thumbnail

    • loadThumbnailLarge | type: boolean | default: false | load large thumbnail

    • loadThumbnailExtraLarge | type: boolean | default: false | load extra large thumbnail

Returns the full module item with all repeatable groups and references. The method is used to retrieve module items via their identifier. Search operations are provided via the search method (…​/module/{module}/search).

Example

Returns a complete record of the Address module with the id 9015:

curl -X "GET" "https://<host>/<application>/ria-ws/application/module/Address/9015" \
  -u <Username>:<Password>

Get the attachment for a module item as a base64 encoded XML

GET http://.../ria-ws/application/module/{module}/{__id}/attachment
  • Parameters:

    • module: Name of the module to get the attachment from

    • __id: ID of the module item to retrieve the attachment for

  • Response body definition: module_1_6.xsd

Get an attachment for a specified module item. You should use the GET method with application/octet-stream Header (described below) that returns the attachment in binary form. The binary file format approach consumes less bandwidth than the xml approach cause of the Base64 encoding that becomes necessary with xml.

Get the attachment for a module item as a binary stream

GET http://.../ria-ws/application/module/{module}/{__id}/attachment
  • Parameters:

    • module: Name of the module to get the attachment from

    • __id: ID of the module item to retrieve the attachment for

  • Request header:

    • Accept: application/octet-stream

  • Response header:

    • Content-Type: application/octet-stream

    • Content-Disposition: attachment;filename={random-file-name}.{file-extension}

  • Response body definition: file as MIME type application/octet-stream

  • Expected response status: 200 (OK)

The request will return status code 200 (OK) if the syntax of the request was correct. The content will be send using the MIME type application/octet-stream and the Content-disposition header with a suggested filename.

Example

Downloads an attachment from the Multimedia record 70078:

curl -O -J -X "GET" "https://<host>/<application>/ria-ws/application/module/Multimedia/70078/attachment" \
	-u <Username>:<Password> \
	-H "Accept: application/octet-stream"

Get the thumbnail of a module item attachment

GET http://.../ria-ws/application/module/{module}/{__id}/thumbnail
  • Parameters:

    • module: Name of the module to get the attachment thumbnail from

    • __id: ID of the module item to retrieve the attachment thumbnail for

  • Response body definition: image/jpeg

  • URL parameters:

    • size | type: enum of extra_small, small, medium, large, extra_large | default: large | size of the thumbnail that will be returned

Get a thumbnail as image/jpeg

Get the list of writable orgUnits for a module

GET http://.../ria-ws/application/module/{module}/orgunit
  • Parameters:

    • module: Name of the module to get the orgUnits for

  • Response body definition: orgunit_1_0.xsd

  • Example response body: orgunit.xml

Provides a list of all the writable orgUnits for the given module.

Update all fields of a module item

PUT http://.../ria-ws/application/module/{module}/{__id}
  • Parameters:

    • module: Name of the module to update

    • __id: Id of the module item to update

  • Request body definition: module_1_6.xsd

Update a module item with all of its fields and references.

Update a single field of a module item

PUT http://.../ria-ws/application/module/{module}/{__id}/{datafield}
  • Parameters:

    • module: Name of the module to update

    • __id: Id of the module item to update

    • datafield: Name of the field to update

  • Request body definition: module_1_6.xsd

Update a single data field of a module item.

Update all fields of repeatable groups / references

PUT http://.../ria-ws/application/module/{module}/{__id}/{repeatableGroup|reference}/{__referenceId}
  • Parameters:

    • module: Name of the module to update

    • __id: Id of the parent module item to update containing the group / reference

    • repeatableGroup|reference: Name of the reference field or repeatable group containing the item to update

    • __referenceId: Id of the reference to update

  • Request body definition: module_1_6.xsd

Update all fields|attributes of repeatable group|reference.

Example

Updates a repeatable group item of type AdrContactGrp with id 34025 of the Address with id 29011:

curl -X "PUT" "https://<host>/<application>/ria-ws/application/module/Address/29011/AdrContactGrp/34025" \
	-u <Username>:<Password> \
	-H "Content-Type: application/xml" \
	-d $'<application xmlns="http://www.zetcom.com/ria/ws/module">
  <modules>
    <module name="Address">
      <moduleItem id="29011">
        <repeatableGroup name="AdrContactGrp">
          <repeatableGroupItem id="34025">
            <dataField name="ValueTxt">
              <value>max_muster_73</value>
            </dataField>
          </repeatableGroupItem>
        </repeatableGroup>
      </moduleItem>
    </module>
  </modules>
</application>'

Update a single data field of a repeatable group / reference

PUT http://.../ria-ws/application/module/{module}/{__id}/{repeatableGroup|reference}/{__referenceId}/{datafield}
  • Parameters:

    • module: Name of the module to update

    • __id: Id of the parent module item to update containing the group / reference

    • repeatableGroup|reference: Name of the reference field or repeatable group containing the item to update

    • __referenceId: Id of the reference to update

    • datafield: Name of the field of the reference item to update

  • Request body definition: module_1_6.xsd

Update a single data field of a reference or repeatableGroup of a module item.

Add or update the attachment of a module item, as a base64 encoded XML

PUT http://.../ria-ws/application/module/{module}/{__id}/attachment
  • Parameters:

    • module: Name of the module to update

    • __id: Id of the module item to update the attachment for

  • Request body definition: module_1_6.xsd

Add or modify an attachment of a given module item. You should use the PUT method with application/octet-stream Header (described below) that returns the attachment in binary form. The binary file format approach consumes less bandwidth than the xml approach cause of the Base64 encoding that becomes necessary with xml.

Add or update the attachment of a module item, as a binary stream

PUT http://.../ria-ws/application/module/{module}/{__id}/attachment
  • Parameters:

    • module: Name of the module to update

    • __id: Id of the module item to update the attachment for

  • Request header:

    • Accept: application/octet-stream

    • X-File-Name: {original-file-name}.{file-extension} (i.e. document.docx)

  • Expected response status: 204 (No Content)

Add or modify an attachment of a given module item.

Example

Uploads an attachment to the Multimedia record 70078:

curl -X "PUT" "https://<host>/<application>/ria-ws/application/module/Multimedia/70078/attachment" \
  -u <Username>:<Password> \
  -H "X-File-Name: <document>.<extension>" \
	-H "Content-Type: application/octet-stream" \
	--data-binary "@/path/to/file.ext>"

Delete a module item

DELETE http://.../ria-ws/application/module/{module}/{__id}
  • Parameters:

    • module: Name of the module to delete

    • __id: Id of the module item to delete

Delete a module item.

Delete a complete repeatable group / reference

DELETE http://.../ria-ws/application/module/{module}/{__id}/{repeatableGroup|reference}/{__referenceId}
  • Parameters:

    • module: Name of the parent module containing the group / reference item to delete

    • __id: Id of the parent module item containing the group / reference item to delete

    • repeatableGroup|reference: Name of the reference field containing the referenced item to delete

    • __referenceId: ID of the reference item to delete

Delete a repeatable group or reference of a module item.

Example

Delete a repeatable group item of type AdrContactGrp with id 34025 of Address 29011

curl -X "DELETE" "https://<host>/<application>/ria-ws/application/module/Address/29011/AdrContactGrp/34025" \
	-u <Username>:<Password>

Delete a reference contained within a repeatable group

DELETE http://.../ria-ws/application/module/{module}/{__id}/{repeatableGroup}/{__groupId}/{reference}/{__referenceId}
  • Parameters:

    • module: Name of the parent module containing the group with the reference item to delete

    • __id: Id of the parent module item containing the group with the reference item to delete

    • repeatableGroup: Name of the repeatable group field containing the referenced item to delete

    • __groupId: ID of the group item containing the reference item to delete

    • reference: Name of the reference field within the group containing the item to delete

    • __referenceId: Id of the referenced item to delete

Delete a reference of a repeatable group of a module item.

Delete the attachment of a module item

DELETE http://.../ria-ws/application/module/{module}/{__id}/attachment
  • Parameters:

    • module: Name of the module containing the item to delete the attachment for

    • __id: Id of the module to delete the attachment for

Delete the attachment of a module item.

XML Schema

Please find below a list of all XML Schema files used in the module service. The schemas can be used to automatically generate bindings for the web services.

File Description

module_1_6.xsd

Defines the module message format for sending, retrieving data and for module definition

export_1_0.xsd

Defines the format for the export respectively report mechanism

orgunit_1_0.xsd

Defines the format for the orgunit retrieval

search_1_7.xsd

Defines the format to submit search expressions

Examples Postman collection

The downloadable JSON file provides a collection of the examples as described in this document for the popular WebServices tool Postman.

Variables are used in this collection. The variables and mockup values are saved in the properties of the collection itself.

  • Quick overview of the variables:

    • TheUsername : The username which is used to log on

    • ThePassword : The corresponding password to the variable "TheUsername"

    • HostName : The IP or the domain name. E.g. de1.zetcom-group.de, 127.0.0.1:8181, localhost:8080

    • Classifier : Consists of the prefix "MpWeb-" and the name of the instance distributed by zetcom. E.g. MpWeb-mpSpectrumDollySandboxTest

    • ModuleName : The name of the module. E.g. Object, Address, Project, Multimedia etc.

    • ModuleRecordId : The ID of the actual record in a certain module. This value must be an integer. In the graphical user interface this ID usually appears on the top right.

    • VocabularyGroup : The internal name of a vocabulary usually ending with the postfix Vgr. E.g. AccDenominationVgr, ObjValueStatusVgr. In case you have access to the graphical user interface and especially the vocabulary module, the vocabulary module can be used to search for vocabulary groups and their vocabulary nodes. Otherwise the vocabulary service (see above) has to be used.

    • RepeatableGroup : The name of the repeatable group, usually ending with the postfix Grp (e.g. AdrContactGrp, ObjInscriptionGrp). In case you have access to the graphical user interface, it is possible to get the logicalName of a field, repeatable group or reference by pressing F4 and clicking on the GUI component to open the inspector view. The inspector view shows some technical information, including the name of the field, repeatable group or reference it is bound to. Otherwise the full definition can be retrieved with the module definition web service call described on this page.

    • RepeatableGroupItemId : This ID is automatically distributed by the application. In order to obtain the "RepeatableGroupItemId" a GET request through Postman is needed. See example "Get a single module item". This value must be an integer.

    • ExportId : Represents the ID of the Report

File Description

zetcom-postman-coll.json

Web Service API request examples using Postman. Last updated 2020-05-16