OMail2CM User Manual 1.6.0

CALLING THE SERVICE

The API is a REST service which accept the JSON formatted data for creation and update of records in CM.
To explain the RM8 API calls we will be using URL structure as http:/FYBTEST-CM01/oMail2CM_API/
NOTE: This URL is an example which will be used throughout the document to explain the REST calls made to the API. This URL is intended to change as per member?s environment (TEST/PRODUCTION).

REQUEST STRUCTURE

A request to the oMail2CM Web API can be made via HTTP POST or HTTP GET. The endpoints can receive POST request as JSON to create/update the records and GET request to retrieve the details about records and entities related to the requested identifier or type.
For example
The updateDetails for record requires following parameter to update the details in RM8.
? Identifier
? Metadata that needs to be changed
To call the updateDetails endpoint a POST request with URL structure and JSON body will be as follows

RESPONSE STRUCTURE

oMail2CM Web API will respond to all POST request in JSON in the following structure

The ok field will show if the API encountered any error. The field will be set to true if no errors, or false if any. The message field will contain description of the error or a success message. ?

CREATE RECORD

The createRecord endpoint accepts JSON to create records with the requested properties and fields.

REQUEST

JSON BODY

createRecord API endpoint accepts JSON body as input which can comprise of all the mandatory and mon- mandatory fields related to the record. Refer to the request below

REQUEST URL

[CLIENTS URL]/oMail2CM_API/Record/createRecord

SENDING STOCK PROPERTIES

Some sample stock properties
To send a stock property simply send the name of the property ?Title:? followed by the value ?oMail2CM Planning document?

SENDING ASSIGNEE AND NOT ENCLOSING

If you?d like to send assignee and set that as the record?s current location, please ensure you send it after the container.
For Example:

Sending it before the container can cause the assignee to appear as ?At Home? in the container.

SENDING ADDITIONAL FIELDS

In the following example below, we are sending an additional field called Teamwork ID

To send additional fields it?s the same as a stock property whereby you send the name of the additional field ?Teamwork ID? followed by the value ?99999?
?
### SETTING CUSTOM AND OTHER RELATIONSHIPS
The oMail2CM now supports every single relationship type including all the custom relationships.
For related records you can simply use Related Records: which is the equivalent IsRelatedTo.
For alternatively contains please use Alternatively Contains:

Custom and other relationship types can be set as below.
For Example: Setting the relationship type as Custom 1
For single relationships just supply as: "Custom1": 1359210
For multiple relationships supply as "Custom1": "1359210, 1359211"

The following relationship types are available
? IsRelatedTo
? IsTempCopy
? IsRootPart
? DoesSupersede
? IsInSeries
? IsAttachmentOf
? IsVersion
? IsAltIn
? Custom1
? Custom2
? Custom3
? Custom4
? Custom5
? Custom6
? Custom7
? Custom8
? Custom9
? Custom10
? RedactionOf
? DerivedFrom
? ContainsClause
? InSharepointSite
? IsReplyTo

SENDING ACTION INFORMATION

When sending action information, you are required to send the following fields:
? Actions
? Responsible Locations

The following request above would attach a single action to the record using a location with a URI of 9932 as the responsible person.
You can attach more than one action to a record as below by comma separating the values.

They will be attached within Content Manager in order specified in the JSON request.

SENDING SECURITY INFORMATION

The security property is used to set the following:
? Security Level
? Security Caveats

The Security Level is always the first value in the list as you can only ever set one security level.
The Security Caveats are set after this separated by commas for multiple.
The following request would set the Security Level to Top and attach the Security Caveats named Confidential, Employee Folders and Executive.
To send Security Caveats without setting a Security Level leave the first value blank separate with a comma the specify the Security Caveats.

SETTING ACCESS CONTROLS

There are seven access controls you can send as shown below.
You can attach multiple locations (persons, positions, organisations etc) by comma separating them.

You are not required to set access controls. Any requirement to send access controls would be dependent on the client?s configuration. For Example: The document may grab its access controls from its container and therefore they are not required to be sent.

SENDING A FILE NAME AND BASE64STRING VS A LOCATION

The API will allow you to specify either a File Name and Base64String, a Location for the electronic document or a SFTP Location of the electronic document.
You do not need to send all three.
The File Name and Base64String can be send as below.

The Location field is useful if the electronic document already sits locally at the client site.
If supplying a Location, it needs to be a UNC Path that can be accessible by the oMail2CM API.
For Example:

In case of sending the document from a SFTP folder the next information should be required:

RESPONSE

NOTE: The API returns all the Content Manager exceptions as a message back to the requesting application to debug the error. E.g. if there are any missing mandatory fields missing which serving the request a message will be returned regarding failure of request due to missing field.

UPDATE DETAILS

UpdateDetails endpoint accepts JSON to update details related to record type.

REQUEST

JSON BODY

REQUEST URL

[CLIENTS URL]/oMail2CM_API/Record/updateDetails

RESPONSE

ok True, if record is created with any error. Else false
message Description of error if any

CREATE LOCATION

The createLocation endpoint accepts JSON to create locations with the requested properties and fields.

REQUEST

JSON BODY

createLocation API endpoint accepts JSON body as input which can comprise of all the mandatory and mon- mandatory fields related to the location. Refer to the request below

REQUEST URL

[CLIENTS URL]/oMail2CM/location/CreateLocation

Only the Location Type and Name are mandatory

SETTING THE LOCATION TYPE

You can set all location types, but the common uses are ?Person? and ?Organisation?

SENDING ADDITIONAL FIELDS

In the following example below, we are sending an additional field called Teamwork ID

To send additional fields it?s the same as a stock property whereby you send the name of the additional field ?Teamwork ID? followed by the value ?99999?

CREATING AN INTERNAL LOCATION

Typically, most locations will be external but if you need to set an internal location (a staff member) add
?Internal": true,

SETTING LOCATION RELATIONSHIPS

The ?Member Of? field allows you to set what location it will sit under. It?s not mandatory.
"Member Of":"8333"

SETTING ADDRESSES

The format needs to be in ?Address, Suburb, STATE, POSTCODE, COUNTRY?
Not all fields are mandatory however if supplying as blank you still need to include the commas and leave as blank.
For Example: I?m unsure of the STATE so I just supply as blank
?Street Address?:?123 Street Address, Williamstown,3000,COUNTRY?

RESPONSE

NOTE: The API returns all the Content Manager exceptions as a message back to the requesting application to debug the error. E.g. if there are any missing mandatory fields missing which serving the request a message will be returned regarding failure of request due to missing field.

RETRIEVING DETAILS

This part of the request has been sub divided into different API calls to provide extensive retrieval functionality over different properties and fields.
To provide extensive searching functionality, the URL related to each Sub API call can be structured in the following way:

NOTE: Query strings are the same as Content Manager search strings.
In order to get a list of Record Types use the Record Types GET.

RETRIEVING RECORD TYPES

REQUEST URL
[CLIENTS URL]/oMail2CM_API/Record/Recordtypes?query=[QUERY]
EXAMPLE
To retrieve a list of all Record Types that behave as folders
[CLIENTS URL]/oMail2CM_API/Record/Recordtypes?query=behaviour:folder

RETRIEVING ACTIONS

REQUEST URL
[CLIENTS URL]/oMail2CM_API/Record/Actions?query=[QUERY]
EXAMPLE
To retrieve a list of all Actions that are assignable
[CLIENTS URL]/oMail2CM_API//Record/Actions?query=assignable

RETRIEVING CLASSIFICATIONS

REQUEST URL
[CLIENTS URL]/oMail2CM_API/Record/Classifications?query=[QUERY]
EXAMPLE
To retrieve a list of all Classifications that are top level
[CLIENTS URL]/oMail2CM_API/Record/Classifications?query=top

RETRIEVING ADDITIONAL FIELDS

REQUEST URL
[CLIENTS URL]/oMail2CM_API/Record/AdditionalFields?query=[QUERY]
EXAMPLE
To retrieve a list of all Additional Fields that are used for Documents
[CLIENTS URL]/oMail2CM_API/Record/AdditionalFields?query=forRecords:Document

RETRIEVING MANDATORY FIELDS

Retrieving Mandatory fields is different from the previous examples, it only takes 1 parameter, the record type.
REQUEST URL
[CLIENTS URL]/oMail2CM_API/Record/MandatoryFields?query=[Record Type]
EXAMPLE
To retrieve a list of all Mandatory Fields for Documents
[CLIENTS URL]/oMail2CM_API/Record/MandatoryFields?query=Document

RECORDS

Records endpoint returns records details from CM related to the query being sent in the request
### REQUEST

REQUEST URL

[CLIENTS URL]/oMail2CM_API/Record/Records?query=[QUERY]

RESPONSE

This request from the URL above will return all stock properties and additional field for specified record(s)in a JSON format.

SAMPLE QUERIES AND TIPS

It is important to note that the bigger the result set the longer the query will take to return results.
You can speed up queries by breaking them down into logical parts if required.
/Records?query=type:"RECORD TYPE HERE" and registeredon:2017
This would bring you back any records of that Record Type registered in 2017
Some other examples of registeredon are as follows:
? registeredon:today
? registeredon:this week
? registeredon:last week
? registeredon:January 2016
? registeredon:February 2017

RECORDS RESPONSE CUSTOMISATION

You can customise the fields that are returned on the Records response through query params by supplying the name of the stock property of additional field in the URL request.
This helps improve performance by returning only the metadata required.

INCLUDE QUERY PARAMETERS

After the executing the query above the following response is produce:

EXCLUDE QUERY PARAMETERS

Similarly, you can exclude certain additional field or stock field with the example below this will return all meta data except those that are defined in the exclude query params.

Please see the attached record stock properties values

RECORD TYPES

Record Type endpoint return the record types details from CM related to the query being sent in the request

REQUEST

REQUEST URL

[CLIENTS URL]/oMail2CM_API/Record/RecordType?query=all

RESPONSE

LOCATIONS

Locations endpoint return the locations details from CM related to the query being sent in the request. Similar to the record endpoint you can control what metadata is returned through query parameters. As shown in the example below.

REQUEST

REQUEST URL

[CLIENTS URL]/oMail2CM_API/Location/Locations?query=[QUERY]

RESPONSE

This request from the URL above will return all stock properties and additional fields for the location in a JSON format.

LOCATION RESPONSE CUSTOMISATION

INCLUDE QUERY PARAMETERS

EXCLUDE QUERY PARAMETERS

To exclude certain metadata from the response by specifying the name of the stock property or additional field after the exclude= parameter. Each metadata property needs to be comma separated.

Please see attached Location stock properties

CLASSIFICATIONS

Classification endpoint return the classifications details from CM related to the query being sent in the request

REQUEST

REQUEST URL

[CLIENTS URL]/oMail2CM_API/Record/Classification/query=all

RESPONSE

NOTE: CanAttachRecords will only be available if the EDRMS build is 9.0 or higher.

ADDITIONAL FIELDS

Additional Fields endpoint return the Additional Fields details from CM related to the query being sent in the request

REQUEST

REQUEST URL

[CLIENTS URL]/oMail2CM_API/Record/AdditionalFields/query=all

RESPONSE

SUCCESS sends backs the list of JSON object for all the classifications and details that are searched using the requested query.
FAIL: sends back empty list.
Note: Failed response can be changed to a message instead of empty list.

COMMON ERROR MESSAGES

As indicated throughout the document the API will capture messages received from Content Manager. It?s not possible to provide all error messages however most messages will return a meaningful explanation as to why records are not saving.
Below we have explained some of the common messages you may receive and potential causes.
Not supplying a record type can cause the following message.

Not supplying a mandatory field whether it?s a stock property or an additional field. This indicates it must be set as mandatory on the record type.

You have supplied the field however the data contains invalid information. This could be providing a URI of a location that doesn?t existing in the dataset. Such as an author

CONFIGURATION

API configuration can be set through either IIS or web.config file in install directory.

DEBUGGING

API will send all the Content Manager exception messages back to the external application. But for debugging purposes a log file is being created at logPath location (see configure section) which will log all the incoming request to the API. This log file will be created per day.