Integrations & API Version 7.18 This documentation is provided under restrictions on use and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this documentation, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. © 2021 Creatio. All rights reserved. Table of Contents | 3 Table of Contents Integration options 6 Compare integration methods 6 Integration with DataService 7 Integration with OData 8 Integration with custom configuration web service 8 Authentication 8 Disabling the CSRF protection 9 Implement authentication using C# 9 Example implementation algorithm 10 AuthService.svc web-service 11 Request string 12 Request headers 12 Request body 12 HTTP status code 13 Response headers 13 Response body 13 OData 14 OData 4 protocol 14 OData 3 protocol 14 The limitations of OData protocol 16 OData integration examples 17 Stream data type request examples 17 Retrieve data 17 Add data 19 Modify data 24 Delete data 26 Batch request examples 27 Batch request (Content-Type: application/json) 28 Batch request (Content-Type: application/json and Prefer: continue-on-error) 31 Batch request (Content-Type: multipart/mixed) 33 Batch request (Content-Type: multipart/mixed and different sets of requests) 36 WCF client request examples 38 Retrieve a contact collection via a LINQ request. 39 Retrieve a contact collection via an implicit request 40 Retrieve a contact collection via an explicit request 40 CRUD operation examples 41 © 2021 Creatio. All rights reserved. Table of Contents | 4 Odata web service (OData 4) 43 Request string 44 Request headers 46 Request body 46 HTTP status code 47 Response body 48 EntityDataService.svc web service (OData 3) 49 Request string 50 Request headers 52 Request body 53 HTTP status code 53 Response body 54 DataService 55 Resctrictions when using DataService 55 Add a button to create a new record in the [Contacts] section 56 Example implementation algorithm 56 Add a button to read records in the [Contacts] section 58 Example implementation algorithm 58 Filter records in the [Contacts] section 61 Example implementation algorithm 61 Filter records in the [Contacts] section using a macro 65 Example implementation algorithm 66 Update a record in the [Contacts] section 69 Example implementation algorithm 69 Delete a record in the [Contacts] section 73 Example implementation algorithm 73 Add and update a record in the [Contacts] section 77 Example implementation algorithm 77 InsertQuery class 81 Properties 82 The ColumnValues class 83 The Parameter class 84 SelectQuery class 85 Properties 87 The SelectQueryColumns class 89 The ColumnExpression class 89 The Parameter class 92 The ServerESQCacheParameters class 93 Filters class 94 © 2021 Creatio. All rights reserved. Table of Contents | 5 The Filters class 94 The BaseExpression class 97 EntitySchemaQueryMacrosType enumeration 100 UpdateQuery class 101 Properties 102 The ColumnValues class 103 The Parameter class 104 The Filters class 105 DeleteQuery class 105 Properties 106 The Filters class 107 Batch queries 107 Business process service 108 Run business process via web-service 108 Example implementation algorithm 108 Launch the process from a client module 117 Case description 118 Source code 118 Case implementation algorithm 118 ProcessEngineService.svc web-service 123 Request string 124 Request headers 125 Response body 125 Executing a separate element of the business process 126 Using Postman 126 Working with requests in Postman 127 Adding a request 127 Setting up the request 129 Executing the request 131 Saving the request 131 Working with request collections in Postman 132 Adding a collection of requests 132 Adding requests to the collection 134 Setting up variables for the request collection 135 Executing the collection of requests 136 © 2021 Creatio. All rights reserved. Integration options | 6 Integration options Medium Creatio enables a range of methods for integration with third-party software products. Choosing the integration method depends on the client's needs, the type and architecture of third-party software products, and the developer's skills. Compare integration methods A comparison of the main characteristics of the supported methods of integration with Creatio is given in the table. © 2021 Creatio. All rights reserved. Integration options | 7 Comparison of main methods of integration with Creatio Feature DataService OData ProcessEngineService Custom configuration service Supported XML, JSON, XML, JSON XML, JSON XML, JSON formats of JSV, CSV the data exchange Tasks are CRUD CRUD-operations with Launch business All user tasks being solved operations objects, adding and removing processes, pass and that can be with Creatio links, obtaining metadata, return the parameters of solved within objects, data collections, object fields, the launched business the open filtering, and sorting, etc. process, launch Creatio API use of built-in individual elements of a Creatio business process macros Complexity High Medium Low Medium Ways of Forms Forms Forms Anonymous, authentication Forms — depends on service implementation Availability of Creatio .dll Enabled No need No need auxiliary libraries can http://www.odata.org/libraries custom be used only libraries for .NET applications Developer Creatio Microsoft Creatio Creatio A brief description and the main advantages of each of the methods are given below. Integration with DataService The DataService web service is the main link between the Creatio client and server parts. It helps to transfer the data entered by user via user interface to the server-side of the application to further process and save to the database. Key benefits and integration options: Data exchange with XML, JSON, JSV, CSV. © 2021 Creatio. All rights reserved. Authentication | 8 Available operations of creating, reading, updating, and deleting the Creatio objects (CRUD operations). You can use built-in macros and data filtering. User authorization is required for access. Integration with OData Open Data (OData) protocol is an open web protocol for data requests and updates based on the REST architectural approach using Atom/XML and JSON standards. Any third-party application that supports HTTP messaging and can process XML or JSON data can have access to the Creatio data and objects. Data is available as resources addressed through a URI. Access to the data and modification are performed by standard HTTP commands (GET, PUT/PATCH, POST, and DELETE). Key benefits and integration options: Data exchange with XML, JSON. A lot of operations with Creatio objects, including CRUD operations. Convenient functions for working with strings, dates, and time. A large number of custom libraries for working with OData for popular application and mobile platforms. User authorization is required for access. Integration with custom configuration web service Creatio enables to create of custom web services in the configuration that can implement specific integration tasks. Configuration web service is a RESTful service implemented based on WCF technology. Key benefits and integration options: Developer implements data exchange in any convenient way. Developer can implement any operation with Creatio objects, including CRUD operations. User authorization is not required for access. Authentication Medium All external requests to Creatio web services must be authenticated. We have the following authentication types in Creatio: Anonymous authentication. Basic authentication. Forms authentication (Cookie based). Authentication based on the OAuth 2.0 open authorization protocol. The “Forms authentication” is a best practice for integration with the application. To perform the “Forms authentication”, Creatio uses a separate AuthService.svc web service. © 2021 Creatio. All rights reserved. Implement authentication using C%23 | 9 Starting with version 7.10, authentication is protected from CSRF attacks. Note. CSRF (Cross Site Request Forgery) – is a type of attacks for web site visitors based on possible HTTP problems. You need to perform authentication using the AuthService.svc service when integrating with third party applications. After you successfully authenticate, AuthService.svc returns the authentic cookie that must be added to your request. It also returns a cookie containing the CSRF token. This token must be placed in the request header. You can find examples of an authentic cookie below and in the OData and DataService data services. Disabling the CSRF protection Attention.We recommend disabling the CSRF protection only if you use basic authentication. In Creatio, you can disable the CSRF protection both for the whole application or for separate services and methods. 1. Disabling the CSRF protection for all application services In the .\Web.Config and .\Terrasoft.WebApp\Web.Config files, disable the UseCsrfToken setting: <add value="false" key="UseCsrfToken" /> 2. Disabling the CSRF protection for one application service. Use the DisableCsrfTokenValidationForPaths setting in the .\Web.Config file: <add key="DisableCsrfTokenValidationForPaths" value="/ServiceModel/ MsgUtilService.svc" />