

Creatio Connector Reference

Authentication implementation

The Creatio connector uses Forms authentication (cookie-based) to authenticate requests with CreatioCRM and the required cookies are retrieved through basic authentication. The Authentication request is created based on the information including the CreatioCRM user credentials configured in the "init" operation of the connector. Once the Creatio REST API provides the authentication response, it is processed by the connector to derive the cookie values.

The authentication response contains two Auth cookies (“BPMCSRF” and “Cookie”) as HTTP header values.

The REST API calls related to CreatioCRM CRUD operations are expected to have the above cookies as HTTP headers. Therefore, the connector will validate if the authentication headers are present in the incoming API request.

If the authentication headers are present in the API request, the connector will send the original request as it is.

If the HTTP status of the response is 401, 403, 301, and 302 (invalid header value or redirection to regenerate the headers), the connector sends the authentication request again and sets the Auth response header back to the original request and perform the original request.

If the HTTP status of the response is not 401, 403, 301, or 302, the response is returned to the client app.

The reason to retry the API calls when giving HTTP status 401, 403, 301, and 302 by Creatio, is that it returns the HTTP status when authentication fails for some reason and you need to retry this once to succeed with the relevant API calls.

If the headers are not present, the connector sends the authentication request intermediately before the relevant REST API call. After getting the relevant cookie headers, it sends the original request to the Creatio endpoint with the retrieved cookies set as headers and sends back the response.

The authentication request is sent to the Creatio platform and the received response is processed to derive the cookie values that are CSRF token and Cookie header values that contain the necessary auth data for authentication at the Creatio end. These HTTP header values need to be set by the client application when calling any other REST API resource from the Creatio end. After expiry, you will be responsible for getting new CSRF cookie values.

To use the Creatio connector, add the <creatiocrm.init> element in your configuration before carrying out any other Creatio operations.

Operations

The following operations allow you to work with the Documentum Connector. Click an operation name to see parameter details and samples on how to use it.

Initialize the connector

Init

This operation is to create an authentication channel after successful authentication, it will respond back with two main cookie values by WSO2 MI in-order to use subsequent API requests.

The init operation has the following configurations that are required to obtain the authentication cookie information for the rest of the operations.

Parameter Name	Description	Required	Sample Value
hostName	Hostname of the CreatioCRM	Yes	116914-crm-bundle.creatio.com
password	Password to login to CreatioCRM	Yes	Supervisor
username	Username to login to CreatioCRM	Yes	Supervisor
timeout	Timeout value of the Creatio backend	No	6000

Sample Configuration

<creatiocrm.init>
    <hostName>https://<hostname>/</hostName>
    <password>password</password>
    <username>username<username>
</creatiocrm.init>
<creatiocrm.authSession/>

This explains how the API request for the init operation should be and the response coming back from the Creatio connector for the Authentication operation.

Request Header Field	Type	Description
Content-Type	String	application/json

Response Header Field	Type	Value	Description
BPMCSRF	String	The CSRF Token	E.g., bHZfVOIO4.iSuXwMebGibes
Cookie (this is optional)	String	Cookie Value	E.g., UserName=83

Creatio operations

When API authentication fails due to expired/invalid cookies, the creatiocrm.init mediator will be used for the regeneration of authentication header values. Therefore, to avoid authentication failures, ‘creatiocrm.init’ and ‘creatiocrm.authSession’ mediators (as shown above under ‘Init Operation’) should be added just before any of the API resources. Any advanced authentication requirements should be addressed through an API Management solution.

Contact operations

Create Contact

The REST API of Contact creation operation is triggered by the creatiocrm.contactCreate mediator to create a new Contact with a unique id in the CreatioCRM.

The message body for the contact creation will be taken from the payload of the existing message context.

Field	Type	Description	Remarks
Content-Type	String	application/json
BPMCSRF	String	The CSRF Token from the Auth response	E.g., bHZfVOIO4.iSuXwMebGibes
Set-cookie	String	Value of Username cookie from the Auth response	E.g., UserName=83
Cookie (this is optional)	String	Cookie Value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>

<creatiocrm.contactCreate/>

Sample request

{
    "Name": "API Test",
    "AccountId": "e6574af1-3e92-4099-958e-e798f52ee016",
    "JobTitle": "Marketing manager",
    "BirthDate": "0001-01-01T00:00:00Z",
    "Phone": "",
    "MobilePhone": "+1 213 566 34 22",
    "Email": "test@gmail",
    "Completeness": 30,
    "Age": 19
}

Sample response

{
    "@odata.context": "https://116914-crm-bundle.creatio.com/0/odata/$metadata#Contact/$entity",
    "Id": "12d21632-8b20-45d9-942f-20fcbbf2957c",
    "Name": "API Test",
    "OwnerId": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
    "CreatedOn": "2022-04-07T09:37:58.5679414Z",
    "CreatedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
    "ModifiedOn": "2022-04-07T09:37:58.5679414Z",
    "ModifiedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
    "ProcessListeners": 0,
    "Dear": "",
    "SalutationTypeId": "00000000-0000-0000-0000-000000000000",
    "GenderId": "00000000-0000-0000-0000-000000000000",
    "AccountId": "e6574af1-3e92-4099-958e-e798f52ee016",
    "DecisionRoleId": "00000000-0000-0000-0000-000000000000",
    "TypeId": "00000000-0000-0000-0000-000000000000",
    "JobId": "00000000-0000-0000-0000-000000000000",
    "JobTitle": "Marketing manager",
    "DepartmentId": "00000000-0000-0000-0000-000000000000",
    "BirthDate": "0001-01-01T00:00:00Z",
    "Phone": "",
    "MobilePhone": "+1 213 566 34 22",
    "HomePhone": "",
    "Skype": "",
    "Email": "test@gmail",
    "AddressTypeId": "00000000-0000-0000-0000-000000000000",
    "Address": "",
    "CityId": "00000000-0000-0000-0000-000000000000",
    "RegionId": "00000000-0000-0000-0000-000000000000",
    "Zip": "",
    "CountryId": "00000000-0000-0000-0000-000000000000",
    "DoNotUseEmail": false,
    "DoNotUseCall": false,
    "DoNotUseFax": false,
    "DoNotUseSms": false,
    "DoNotUseMail": false,
    "Notes": "",
    "Facebook": "",
    "LinkedIn": "",
    "Twitter": "",
    "FacebookId": "",
    "LinkedInId": "",
    "TwitterId": "",
    "[email protected]": "Contact(12d21632-8b20-45d9-942f-20fcbbf2957c)/ContactPhoto",
    "[email protected]": "Contact(12d21632-8b20-45d9-942f-20fcbbf2957c)/ContactPhoto",
    "[email protected]": "application/octet-stream",
    "TwitterAFDAId": "00000000-0000-0000-0000-000000000000",
    "FacebookAFDAId": "00000000-0000-0000-0000-000000000000",
    "LinkedInAFDAId": "00000000-0000-0000-0000-000000000000",
    "PhotoId": "00000000-0000-0000-0000-000000000000",
    "GPSN": "",
    "GPSE": "",
    "Surname": "Test",
    "GivenName": "API",
    "MiddleName": "",
    "Confirmed": true,
    "IsNonActualEmail": false,
    "Completeness": 30,
    "LanguageId": "6ebc31fa-ee6c-48e9-81bf-8003ac03b019",
    "Age": 19,
    "IsEmailConfirmed": false
}

Get Contact

The contactGet operation is used to retrieve existing contact details from CreatioCRM with the provided ID. If the given ID does not exist in the CreatioCRM, this will return 404 HTTP status code.

Field	Type		Description	Remarks
BPMCSRF	String		The CSRF Token from the Auth response	E.g., bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	E.g., UserName=83
Cookie (this is optional)	String		Cookie Value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.contactGet>
    <id>{$ctx:id}</id>
</creatiocrm.contactGet>

Sample response

{
    "@odata.context": "https://116914-crm-bundle.creatio.com/0/odata/$metadata#Contact/$entity",
    "Id": "12d21632-8b20-45d9-942f-20fcbbf2957c",
    "Name": "API Test",
    "OwnerId": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
    "CreatedOn": "2022-04-07T09:37:58.5679414Z",
    "CreatedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
    "ModifiedOn": "2022-04-07T09:37:58.5679414Z",
    "ModifiedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
    "ProcessListeners": 0,
    "Dear": "",
    "SalutationTypeId": "00000000-0000-0000-0000-000000000000",
    "GenderId": "00000000-0000-0000-0000-000000000000",
    "AccountId": "e6574af1-3e92-4099-958e-e798f52ee016",
    "DecisionRoleId": "00000000-0000-0000-0000-000000000000",
    "TypeId": "00000000-0000-0000-0000-000000000000",
    "JobId": "00000000-0000-0000-0000-000000000000",
    "JobTitle": "Marketing manager",
    "DepartmentId": "00000000-0000-0000-0000-000000000000",
    "BirthDate": "0001-01-01T00:00:00Z",
    "Phone": "",
    "MobilePhone": "+1 213 566 34 22",
    "HomePhone": "",
    "Skype": "",
    "Email": "test@gmail",
    "AddressTypeId": "00000000-0000-0000-0000-000000000000",
    "Address": "",
    "CityId": "00000000-0000-0000-0000-000000000000",
    "RegionId": "00000000-0000-0000-0000-000000000000",
    "Zip": "",
    "CountryId": "00000000-0000-0000-0000-000000000000",
    "DoNotUseEmail": false,
    "DoNotUseCall": false,
    "DoNotUseFax": false,
    "DoNotUseSms": false,
    "DoNotUseMail": false,
    "Notes": "",
    "Facebook": "",
    "LinkedIn": "",
    "Twitter": "",
    "FacebookId": "",
    "LinkedInId": "",
    "TwitterId": "",
    "[email protected]": "Contact(12d21632-8b20-45d9-942f-20fcbbf2957c)/ContactPhoto",
    "[email protected]": "Contact(12d21632-8b20-45d9-942f-20fcbbf2957c)/ContactPhoto",
    "[email protected]": "application/octet-stream",
    "TwitterAFDAId": "00000000-0000-0000-0000-000000000000",
    "FacebookAFDAId": "00000000-0000-0000-0000-000000000000",
    "LinkedInAFDAId": "00000000-0000-0000-0000-000000000000",
    "PhotoId": "00000000-0000-0000-0000-000000000000",
    "GPSN": "",
    "GPSE": "",
    "Surname": "Test",
    "GivenName": "API",
    "MiddleName": "",
    "Confirmed": true,
    "IsNonActualEmail": false,
    "Completeness": 30,
    "LanguageId": "6ebc31fa-ee6c-48e9-81bf-8003ac03b019",
    "Age": 19,
    "IsEmailConfirmed": false
}

Update Contact

The contactUpdate operation is used to update existing contact details in the CreatioCRM.

If the given ID does not exist in the CreatioCRM, this will create a new contact with the given ID. The message body for the contact update will be taken from the payload of the existing message context.

Field	Type		Description	Remarks
BPMCSRF	String		The CSRF Token from the Auth response	E.g., bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	E.g., UserName=83
Cookie (this is optional)	String		Cookie Value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.contactUpdate>
    <id>{$ctx:id}</id>
</creatiocrm.contactUpdate>

Sample request

{
    "Name": "API Test",
    "AccountId": "e6574af1-3e92-4099-958e-e798f52ee016",
    "JobTitle": "Marketing manager",
    "BirthDate": "0001-01-01T00:00:00Z",
    "Phone": "",
    "MobilePhone": "+1 213 566 34 22",
    "Email": "test@gmail",
    "Completeness": 30,
    "Age": 19
}

Delete Contact

The contactDelete operation is used to delete a contact that already exists in the CreatioCRM with given unique ID.

If the given ID does not exist in the CreatioCRM this will return 404 HTTP status code

Field	Type		Description	Remarks
BPMCSRF	String		The CSRF Token from the Auth response	E.g., bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	E.g., UserName=83
Cookie (this is optional)	String		Cookie Value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.contactDelete>
    <id>{$ctx:id}</id>
</creatiocrm.contactDelete>

Case operations

Create Case

Creatio caseCreate operation used in MI mediation to create a new case with a unique ID in the CreatioCRM.

The message body for the case creation will be taken from the payload of the existing message context.

Field	Type		Description	Remarks
BPMCSRF	String		The CSRF Token from the Auth response	E.g., bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	E.g., UserName=83
Cookie (this is optional)	String		Cookie value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.caseCreate/>

Sample request

{
    "Number": "SR00000040",
    "RegisteredOn": "2021-07-16T11:00:00Z",
    "Subject": "Consultation on functionality",
    "Symptoms": "Comparison of different DBMS in accordance with the customer's needs",
    "Notes": "",
    "AccountId": "ff7e089f-1fe9-4ca9-bc30-2d76ad39d178",
    "ContactId": "00b34750-2feb-4545-b233-153502326f3c",
    "SolutionRemains": 0.0
}

Get case

The caseGet operation is used to retrieve the case already exist in the reatioCRM with the unique ID.

If the given ID does not exist in the CreatioCRM, this will return a 404 HTTP status code.

Field	Type		Description	Remarks
BPMCSRF	String		The CSRF Token from the Auth response	E.g., bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	E.g., UserName=83
Cookie (this is optional)	String		Cookie Value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.caseGet/>
    <id>{$ctx:uri.var.id}</id>
</creatio.caseGet>

Update case

The caseUpdate operation is used to update the existing case details in the CreatioCRM.

If the given ID does not exist in the CreatioCRM, this will create new contact with the given ID.

Field	Type		Description	Remarks
BPMCSRF	String		The CSRF Token from the Auth response	E.g., bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	E.g., UserName=83
Cookie (this is optional)	String		Cookie value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.caseUpdate/>
    <id>{$ctx:uri.var.id}</id>
</creatio.caseUpdate>

Sample request

{
    "Number": "SR00000040",
    "RegisteredOn": "2021-07-16T11:00:00Z",
    "Subject": "Consultation on functionality",
    "Symptoms": "Comparison of different DBMS in accordance with the customer's needs",
    "Notes": "",
    "AccountId": "ff7e089f-1fe9-4ca9-bc30-2d76ad39d178",
    "ContactId": "00b34750-2feb-4545-b233-153502326f3c",
    "SolutionRemains": 0.0
}

Delete case

The caseDelete operation is used to delete a case that already exists in the CreatioCRM with given unique ID.

If the given ID does not exist in the CreatioCRM this will return 404 HTTP status code.

Field	Type		Description	Remarks
BPMCSRF	String		The CSRF Token from the Auth response	E.g., bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	E.g., UserName=83
Cookie (this is optional)	String		Cookie value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.caseDelete>
    <id>{$ctx:uri.var.id}</id>
</creatio.caseDelete>

Account operations

Account Create

Creatio accountCreate operation is used in MI mediation to create a new account with a unique ID in Creatio.

The message body for the account creation will be taken from the payload of the existing message context.

Field	Type		Description	Remarks
Content-Type	String		application/json
BPMCSRF	String		The CSRF Token from the Auth response	Ex: bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	Ex: UserName=83
Cookie (this is optional)	String		Cookie Value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.accountCreate/> 

Sample request

{
    "Name": "API 1",
    "ProcessListeners": 0,
    "Phone": "+1 206 480 3801",
    "AdditionalPhone": "+1 206 480 4495",
    "Fax": "",
    "Web": "www.infocom-global.com",
    "Address": "48 Pilgrim Street",
    "Notes": ""
}

Get Account

The accountGet operation is used to retrieve the account that already exists in the CreatioCRM with the unique ID.

If the given ID does not exist in the CreatioCRM, this will return a 404 HTTP status code.

Field	Type		Description	Remarks
BPMCSRF	String		The CSRF Token from the Auth response	Ex: bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	Ex: UserName=83
Cookie (this is optional)	String		Cookie Value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.accountGet>
    <id>{$ctx:uri.var.id}</id>
</creatio.accountGet>

Update Account

The accountUpdate operation is used to update the existing account details in the CreatioCRM.

If the given ID does not exist in the CreatioCRM this will create a new account with the given ID.

Field	Type		Description	Remarks
BPMCSRF	String		The CSRF Token from the Auth response	E.g., bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	E.g., UserName=83
Cookie (this is optional)	String		Cookie value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.accountUpdate/>
    <id>{$ctx:uri.var.id}</id>
</creatio.accountUpdate>

Sample request

{
    "Name": "API 1",
    "ProcessListeners": 0,
    "Phone": "+1 206 480 3801",
    "AdditionalPhone": "+1 206 480 4495",
    "Fax": "",
    "Web": "www.infocom-global.com",
    "Address": "48 Pilgrim Street",
    "Notes": ""
}

Delete Account

The accountDelete operation is used to delete an account that already exists in the CreatioCRM with a given unique ID.

If the given ID does not exist in the CreatioCRM, this will return a 404 HTTP status code.

Field	Type		Description	Remarks
BPMCSRF	String		The CSRF Token from the Auth response	E.g., bHZfVOIO4.iSuXwMebGibes
Set-cookie	String		Value of Username cookie from the Auth response	E.g., UserName=83
Cookie (this is optional)	String		Cookie value from the Auth response

Sample configuration

<creatiocrm.init>
    <hostName>https://creatio-hostname</hostName>
    <password>creatio-username</password>
    <username>creatio-password</username>
</creatiocrm.init>
<creatiocrm.accountDelete/>
    <id>{$ctx:uri.var.id}</id>
</creatio.accountDelete>

Top