Resco CRM Connector

Resco CRM Connector is a group of web API services that you can use to connect your third-party backend to Resco Cloud to exchange data between the systems. These are the components involved in the Resco CRM Connector.

• Your system: any CRM/ERP system

• Resco CRM Connector: Synchronization module between your backend and Resco Cloud

• Resco Cloud: Fully customizable backend for Resco mobile apps

• Resco mobile apps: Any of the end-user applications customized for Resco Cloud, such as Resco Mobile CRM

Resco Cloud and mobile apps are provided by Resco. Resco Cloud allows you to define a schema and store data for mobile apps, which is used to display the data.

You can now build your own Resco CRM Connector to enable the synchronization between your backend system and the Resco Cloud. Resco Cloud acts as a passive module — it does not initiate any synchronization. Mobile apps must initiate the synchronization process to download/upload data. This also applies to Resco CRM Connector. It must determine when/whether to synchronize ERP system data with data stored on the Resco Cloud. For example, every hour, every day, etc., depends on how current the data must be on the client. To check whether there are new/updated data on the Resco Cloud use “GetMaxRowVersion” web service method to get the current row version. If the current row version changed from the last stored row version, there are new changes available on the Resco Cloud.

Available APIs

Resco CRM Connector offers multiple APIs:

• REST data service - a set of REST web service methods divided into metadata service and data service

• OData service

• Questionnaire OData service - read-only OData v4 API service for accessing questionnaire results

• Resco Cloud Client web services API

This article describes the REST data service.

Data types

• UniqueIdentifier

• String

• Integer

• Float

• Decimal

• DateTime

• Picklist

• PicklistMap

• Boolean

• Money

• Binary

• Lookup

• RowVersion

• PartyList

By default, the data type format in data service requests and responses is in invariant culture (for example, the decimal separator is always a dot).

Date fields are in UTC time, in the following format: yyyy-MM-ddTHH:mm:ssZ; for example, 2020-12-12T09:00:00. Optionally, you can use syntax defined in RFC 3339 to modify this format.

Lookup fields are essentially strings in the following formats:

• entity:id (for create/update requests)

• entity:id:name (for fetch requests)

PartyList fields use the following format (parts in square brackets are optional):

<party [addressused='rajesh@example.com']>entity:id[:name]</party>
<party [addressused='howard@example.com']>entity:id[:name]</party>
...

Data service

Data service helps you access and manipulate data on Resco CRM server. The web service URL depends on server settings; whether the server uses domain organization selection or simple URL organization selection.

• URL organization base web service URL is: https://example.com/rest/v1/data/{organization}

• Domain organization base web service URL is: https://{organization}.example.com/rest/v1/data

Examples

• Resco Cloud server uses the following domain organization selection: https://{organization}.app.resco.net/rest/v1/data

• Resco Inspections cloud server uses the following domain organization selection: https://inspections.resco.net/rest/v1/data/{organization}

• Resco Routes cloud server uses the following domain organization selection: https://routes.resco.net/rest/v1/data/{organization}

Web request requirements

Method: GET/POST

Content-Type: application/xml; charset=utf-8

Authorization: Basic BASE64(login:password)

Methods

POST WhoAmI

Return organization ID and user ID.

No parameters.

Sample URL: https://{organization}.app.resco.net/rest/v1/data/WhoAmI

Response:

<?xml version=“1.0” encoding=“utf-8“?>
<WhoAmI xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance“>          
 <OrganizationId>87ddc2f8-d0d1-4ad6-a925-5765a7a46edd</ OrganizationId>          
 <UserId>601d9d17-89b4-e111-9c9a-00155d0b710a</UserId>
</WhoAmI>

POST GetMaxRowVersion

Return max row version for the database. Row version is counter of every change in database. It helps to determine changes from last synchronization. Each entity has system attribute “rowversion” which determine the version (or timestamp) of last change for the specified row.

No parameters.

Sample URL: https://{organization}.app.resco.net/rest/v1/data/GetMaxRowVersion

Response:

<?xml version=“1.0” encoding=“utf-8“?>
<string>3665</string>

POST GetRecordCount

Get the number of entity records.

Sample URL: https://{organization}.app.resco.net/rest/v1/data/GetRecordCount

Examples of body requests:

<Entities>
   <Entity>activitypointer</Entity>
   <Entity>contact</Entity>
</Entities>

Response:

<ArrayOfGetRecordCountResult xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <GetRecordCountResult name="activitypointer" count="69"/>
    <GetRecordCountResult name="account" count="19"/>
</ArrayOfGetRecordCountResult>

GET Select

Template URL: .../{entity}?$select={select}&$filter={filter}&$orderby={orderby} &$skip={skip}&$top={top}

Returns list of entities.

Parameters:

A condition is defined like: {left identifier} {comparison statement} {right identifier} {and/or} .... The left identifier is always the attribute name.

Comparison statements can be any of following:

Right identifier can be any of following:

Conditions can be joined using:

Sample URL: https://{organization}.app.resco.net/rest/v1/data/account?$select=name,address1_city,emailaddress1&$filter=name%20LIKE%20'C%'&$orderby=address1_city&$skip=2&$top=5

Response:

<?xml version=“1.0” encoding=”utf-8“?>
<EntitySet xmlns=“http://schemas.resco.net/XRM/OrganizationService“>
 <Metadata PrimaryEntity=“account“>
  <Attributes>
   <Attribute EntityName=“account” AttributeName=“name” Name=“name” Type=“String“/>
   <Attribute EntityName=“account” AttributeName=“address1_city” Name=“address1 _city” Type=“String“/>
   <Attribute EntityName=“account” AttributeName=“emailaddress1” Name=“emailaddress1” Type=“String“/>
   <Attribute EntityName=“account” AttributeName=“id” Name=”id” Type=“UniqueIdentifier“/>
  </Attributes>
 </Metadata>
 <Entities>
  <Entity EntityName=“account“>
   <name>Cash and Carry Bikes</name>
   <address1_city>Dallas</address1_city>
   <emailaddress1>someone@example.com</emailaddress1>
   <id>b9ca6c78-4e0b-df11-a3d5-0003ff9c98bb</id>
  </Entity>
  <Entity EntityName=“account“>
   <name>Convenient Bike Shop</name>
   <address1_city>Everett</address1_city>
   <emailaddress1>someone@example.com</emailaddress1>
   <id>bdca6c78-4e0b-df11-a3d5-0003ff9c98bb</id>
  </Entity>
   <Entity EntityName=“account“>
   <name>Cheap n Best bikes</name>
   <address1_city>Redmond</address1_city>
   <emailaddress1>someone@example.com</emailaddress1>
   <id>bbca6c78-4e0b-df11-a3d5-0003ff9c98bb</id>
  </Entity>
   <Entity EntityName=“account“>
   <name>Cool Ride Store</name>
   <address1_city>Seattle</address1_city>
   <emailaddress1>someone@example.com</emailaddress1>
   <id>beca6c78-4e0b-df11-a3d5-0003ff9c98bb</id>
  </Entity>
   <Entity EntityName=“account“>
   <name>Certified Bicycle Supply</name>
   <address1_city>West Covina</address1_city>
   <emailaddress1>someone@example.com</emailaddress1>
   <id>baca6c78-4e0b-df11-a3d5-0003ff9c98bb</id>
  </Entity>
 </Entities>
</EntitySet>

POST Fetch

Fetch query. Return list of entities defined by fetch.

Sample URL: https://{organization}.app.resco.net/rest/v1/data

Request:

<fetch page=“2 ” count=“5” paging-cookie=“optional PagingCookie from previous fetch“>
 <entity name=“account“>
  <attribute name=“id” />
  <attribute name=“name” />
  <order attribute=“name” descending=“true” />
  <filter>
   <condition attribute=“name” operator=“like” value=“b%” />
  </filter>
 </entity>
</fetch>

Response:

<?xml version=“1.0” encoding=”utf-8“?>
<EntitySet xmlns=“http://schemas.resco.net/XRM/OrganizationService“>
 <Metadata PrimaryEntity=“account“>
  <Attributes>
   <Attribute EntityName=“account” AttributeName=“id” Type=“UniqueIdentifier“/>
   <Attribute EntityName=“account” AttributeName=“name” Name=“id” Name=“name” Type=“String“/>
  </Attributes>
 </Metadata>
 <Entities>
  <Entity EntityName=“account“>
   <id>b3ca6c78-4e0b-df11-a3d5-0003ff9c98bb</id>
   <name>Bikes unlimited</name>
  </Entity>
  <Entity EntityName=“account“>
   <id>b2ca6c78-4e0b-df11-a3d5-0003ff9c98bb</id>
   <name>Bike-o-maniac store</name>
  </Entity>
  <Entity EntityName=“account“>
   <id>b1ca6c78-4e0b-df11-a3d5-0003ff9c98bb</id>
   <name>Bike Universe</name>
  </Entity>
  <Entity EntityName=“account“>
   <id>b0ca6c78-4e0b-df11-a3d5-0003ff9c98bb</id>
   <name>Bike Products and Accessories</name>
  </Entity>
  <Entity EntityName=“account“>
   <id>afca6c78-4e0b-df11-a3d5-0003ff9c98bb</id>
   <name>Bike Experts</name>
  </Entity>
 </Entities>
 <MoreRecords>true</MoreRecords>
 <PagingCookie>&lt;cookie page=”2″&gt;&lt;name last=”Bike  Experts” descending=”1″ /&gt;&lt;id last=”afca6c78-4e0b-df11-a3d5-0003ff9c98bb” /&gt;&lt;/cookie&gt;</PagingCookie>
</EntitySet>

POST Create

Create entity and return entity ID. Optional, primary key can be specified by “PrimaryKey” attribute.

Default PrimaryKey is “id”.

Sample URL: https://{organization}.app.resco.net/rest/v1/data/Create

Request:

<Entity EntityName='account' [PrimaryKey='name;address1_city']>
 <id>1607A7F7-C16F-4E19-849C-BAD37FF59F5C</id>
 <name>My Name</name>
 <address1_city>Bratislava</address1_city>
 <revenue>123456.789</revenue>
</Entity>

Response:

<?xml version=“1.0” encoding=“utf-8“?>
<guid>1607a7f7-c16f-4e19-849c-bad37ff59f5c</guid>

POST CreateMultiple

Create multiple entities. The entity is defined same as for Create method.

Sample URL: https://{organization}.app.resco.net/rest/v1/data/CreateMultiple

Request:

<Entities xmlns='http://schemas.resco.net/XRM/EntitySet'>
 <Entity EntityName='account'>
  <id>FE400D92-EFD6-4856-A0B4-94C63212D5C8</id>
  <name>My Name 1</name>
  <address1_city>Bratislava</address1_city>
  <revenue>123456.789</revenue>
 </Entity>
 <Entity EntityName='account'>
  <id>D008549E-842F-46EC-9F76-ECC5F20A550D</id>
  <name>My Name 2</name>
  <address1_city>Bratislava</address1_city>
  <revenue>987654.321</revenue>
 </Entity>
</Entities>

POST Update?$create={create}

Update entity. Optional, the primary key can be specified by “PrimaryKey” attribute. Default PrimaryKey is “id”.

Parameter:

{create} (optional) — Determine whether the entity should be created if it does not exist.

Sample URL: https://{organization}.app.resco.net/rest/v1/data/Update

Optional URL: https://{organization}.app.resco.net/rest/v1/data/Update?$create=true

Request:

<Entity EntityName='account' [PrimaryKey='name;address1_city']>
 <id>1607A7F7-C16F-4E19-849C-BAD37FF59F5C</id>
 <name>My Name 2</name>
 <address1_city>Bratislava</address1_city>
 <revenue>987654.321</revenue>
</Entity>

POST UpdateMultiple?$create={create}

Update multiple entities. The entity is defined the same way as for Update method.

Parameter:

{create} (optional) — Determine whether the entity should be created if it does not exist.

Sample URL: https://{organization}.app.resco.net/rest/v1/data/UpdateMultiple

Optional URL: https://{organization}.app.resco.net/rest/v1/data/UpdateMultiple?$create=true

Request:

<Entities xmlns='http://schemas.resco.net/XRM/EntitySet'>
 <Entity EntityName='account'>
  <id>FE400D92-EFD6-4856-A0B4-94C63212D5C8</id>
  <name>My Name 1</name>
  <address1_city>Bratislava</address1_city>
  <revenue>123456.789</revenue>
 </Entity>
 <Entity EntityName='account'>
  <id>D008549E-842F-46EC-9F76-ECC5F20A550D</id>
  <name>My Name 2</name>
  <address1_city>Bratislava</address1_city>
  <revenue>987654.321</revenue>
 </Entity>
</Entities>

POST Delete

Delete entity. Optional, the primary key can be specified by “PrimaryKey” attribute. Default PrimaryKey is “id”.

Sample URL: https://{organization}.app.resco.net/rest/v1/data/Delete

Request:

<Entity EntityName='account'>
 <id>1607A7F7-C16F-4E19-849C-BAD37FF59F5C</id>
</Entity>

With PrimaryKey:

<Entity EntityName='account' PrimaryKey='name;address1_city'>
 <name>My Name 3</name>
 <address1_city>Bratislava</address1_city>
</Entity>

POST DeleteMultiple

Delete multiple entities. The entity is defined the same way as for Delete method.

Sample URL: https://{organization}.app.resco.net/rest/v1/data/DeleteMultiple

Request:

<Entities xmlns='http://schemas.resco.net/XRM/EntitySet'>
 <Entity EntityName='account'>
  <id>FE400D92-EFD6-4856-A0B4-94C63212D5C8</id> </Entity>
 <Entity EntityName='account'>
  <id>D008549E-842F-46EC-9F76-ECC5F20A550D</id>
 </Entity>
</Entities>

POST Execute

Allow to execute specified operation on entity, such as Create, Update, Upsert and Delete.

Action:

• Create – Create entity

• Update – Update entity

• Upsert – If exist, Update entity; otherwise Create entity

• Delete – Delete entity

Sample URL: https://{organization}.app.resco.net/rest/v1/data/Execute

Request:

<Entity EntityName='account' Action='Create' [PrimaryKey='name;address1_city'] xmlns='http://schemas.resco.net/XRM/Execute'> <!-- parameter in [] is optional -->
 <id>1607A7F7-C16F-4E19-849C-BAD37FF59F5C</id>
 <name>My Name</name>
 <address1_city>Bratislava</address1_city>
 <revenue>123456.789</revenue>
</Entity>

Response:

<Response Action=“Create” xmlns=“http://schemas.resco.net/XRM/Execute“>
 <Result Type=“guid“>1607a7f7-c16f-4e19-849c-bad37ff59f5c</Result>
</Response>

POST ExecuteMultiple

Allow to execute specified operations on multiple entities, such as Create, Update, Upsert, and Delete.

• ContinueOnError – Determine whether to continue executing an operation on error.

• TransactionType – Determine transaction operation:

• None – execute multiple will not run in a transaction

• RollbackOnError – execute multiple transaction will roll back on error

• CommitOnError – execute multiple transaction will commit on error

Action:

• Create – Create entity

• Update – Update entity

• Upsert – If exist, Update entity; otherwise Create entity

• Delete – Delete entity

Sample URL: https://{organization}.app.resco.net/rest/v1/data/ExecuteMultiple

Request:

<ExecuteMultiple TransactionType='RollbackOnError' ContinueOnError='false' xmlns='http://schemas.resco.net/XRM/Execute'>
 <Entity EntityName='account' Action='Create'>
  <id>1607A7F7-C16F-4E19-849C-BAD37FF59F5C</id>
  <name>My Name</name>
  <address1_city>Bratislava</address1_city>
  <revenue>123456.789</revenue>
 </Entity>
 <Entity EntityName='account' Action='Update'>
  <id>1607A7F7-C16F-4E19-849C-BAD37FF59F5C</id>
  <name>My Name 2</name>
 </Entity>
 <Entity EntityName='account' Action='Upsert'>
  <id>2607A7F7-C16F-4E19-849C-BAD37FF59F5C</id>
  <name>My Name 3</name>
  <revenue2>987654.321</revenue2>
 </Entity>
 <Entity EntityName='account' Action='Delete'>
  <id>1607A7F7-C16F-4E19-849C-BAD37FF59F5C</id>
 </Entity>
</ExecuteMultiple>

Response:

<?xml version=“1.0” encoding=“utXRMf-8“?>
<MultipleResponse xmlns=“http://schemas.resco.net/XRM/Execute“>
 <Response Action=“Create“>
  <Result Type=“guid“>1607a7f7-c16f-4e19-849c-bad37ff59f5c</Result> </Response>
 <Response Action=“Update“>
  <Result Type=“bool“>true</Result>
 </Response>
 <Response Action=“Upsert“>
  <Fault xmlns=“http://schemas.resco.net/XRM/XRMServiceError“>
   <Code>500</Code>
   <Reason>KeyNotFoundException</Reason>
   <Detail>The given attribute 'revenue2' was not present in the entity metadata.</Detail>
   <StackTrace>…</StackTrace>
  </Fault>
 </Response>
 <Response Action=“Delete“>
  <Result Type=“bool“>true</Result>
 </Response>
</MultipleResponse>

POST Export

Export the organization data and metadata.

Sample URL:

https://{organization}.app.resco.net/rest/v1/data/{organization}/Export

Example of a body request:

<ExportRequest>
    <Type>Metadata Data Localization Process Plugin Project</Type>
    <Entities>
        <!-- records of these entities will be exported -->
        <Entity>account</Entity>
        <Entity>contact</Entity>
    </Entities>
</ExportRequest>

Type defines what should be exported, e.g if you want to export projects only: <Type>Project</Type>. If you want to export all, use <Type>All</Type>

Response: stream

POST Import

Import the organization data and metadata.

Sample URL:

https://{organization}.app.resco.net/rest/v1/data/{organization}/Import?mode={mode}&publish={publish}

Mode:

• Import = 0 - Apply changes from import schema, but do not remove missing entities or attributes

• Update = 2 - Apply changes from import schema, but remove missing entities or attributes to match exactly imported schema. Loss of data may occur on removed entities or attributes.

Publish:

• true - import will be applied

• false - preview only (what will be changed/imported)

Body:

Binary data (exported organization zip file)

If you want to enable asynchronous data import, add the following key-value pair to the header:

Key: Prefer
Value: respond-async

POST ExportProject

Export the complete app project definition to a file. You need to specify project name or ID as a parameter.

Sample URL:

https://{organization}.app.resco.net/rest/v1/data/ExportProject?$id={id}

https://{organization}.app.resco.net/rest/v1/data/ExportProject?$name={name}

Response: Binary project data.

POST ImportProject (and publish)

Replace the content of an existing app project with the imported file. Specify destination project ID or name. The project must already exist. Use &$publish=true to automatically publish the project.

Sample URL:

https://{organization}.app.resco.net/rest/v1/data/ImportProject?$id={id}&$publish={publish}

https://{organization}.app.resco.net/rest/v1/data/ImportProject?$name={name}&$publish={publish}

BODY:

Binary project data.

POST GenerateReport

Generate a mobile report.

Sample URL:

https://{organization}.app.resco.net/rest/v1/data/GenerateReport

Examples of body requests:

a) Directly define report's data source record as entityid

<GenerateReportRequest>
  <ReportId>07e91ed7-ab9e-4807-acaa-27b8791451e0</ReportId>
  <EntityId>022e0024-35ca-41ba-a8cc-2f5ff304a919</EntityId>
  <GenerateReportFormat>Pdf</GenerateReportFormat>
  <Variables>
    <Variable name="name1">value1</Variable>
    <Variable name="name2">value2</Variable>
  </Variables>
</GenerateReportRequest>

b) Fetch for report's data source records

<GenerateReportRequest>
    <ReportId>bbaade3e-0c9d-41c8-af0f-cc7b8c2b21bd</ReportId>
    <Fetch>
        <entity name="account">
            <attribute name="id"/>
            <filter>
                <condition attribute="id" operator="in">
                    <value>190C065A-9A2D-454A-A6BA-AAA29718C101</value>
                </condition>
            </filter>
        </entity>
    </Fetch>
    <Variables>
        <Variable name="name1">value2</Variable>
        <Variable name="name2">value1</Variable>
    </Variables>
    <GenerateReportFormat>Pdf</GenerateReportFormat>
</GenerateReportRequest>

c) Request with custom report body.

<GenerateReportRequest>
  <ReportId>07e91ed7-ab9e-4807-acaa-27b8791451e0</ReportId>
  <Data>&lt;Report&gt;&lt;Styles&gt;&lt;Style Name=&quot;H1&quot;&gt;&lt;Background&gt;#0026d658&lt;/Background&gt;&lt;BorderColor&gt;#00000000&lt;/BorderColor&gt;&lt;BorderThickness&gt;0,0,0,0&lt;/BorderThickness&gt;&lt;FontSize&gt;15&lt;/FontSize&gt;&lt;FontWeight&gt;Normal&lt;/FontWeight&gt;&lt;Foreground&gt;#FF22e675&lt;/Foreground&gt;&lt;HorizontalAlignment&gt;Near&lt;/HorizontalAlignment&gt;&lt;Margin&gt;0,0,0,0&lt;/Margin&gt;&lt;Padding&gt;0,0,0,0&lt;/Padding&gt;&lt;VerticalAlignment&gt;Near&lt;/VerticalAlignment&gt;&lt;/Style&gt;&lt;Style Name=&quot;Normal&quot;&gt;&lt;Background&gt;#00000000&lt;/Background&gt;&lt;BorderColor&gt;#00000000&lt;/BorderColor&gt;&lt;BorderThickness&gt;0,0,0,0&lt;/BorderThickness&gt;&lt;FontSize&gt;10&lt;/FontSize&gt;&lt;FontWeight&gt;Normal&lt;/FontWeight&gt;&lt;Foreground&gt;#FF000000&lt;/Foreground&gt;&lt;HorizontalAlignment&gt;Near&lt;/HorizontalAlignment&gt;&lt;Margin&gt;0,0,0,0&lt;/Margin&gt;&lt;Padding&gt;0,0,0,0&lt;/Padding&gt;&lt;VerticalAlignment&gt;Near&lt;/VerticalAlignment&gt;&lt;/Style&gt;&lt;/Styles&gt;&lt;Variables&gt;&lt;Variable Name=&quot;src&quot; Type=&quot;Fetch&quot; Required=&quot;false&quot; Visible=&quot;false&quot; Source=&quot;true&quot; Lazy=&quot;true&quot; Fetch=&quot;&amp;lt;fetch&amp;gt;&amp;lt;entity name=&amp;quot;account&amp;quot;/&amp;gt;&amp;lt;/fetch&amp;gt;&quot;/&gt;&lt;Variable Name=&quot;str&quot; Type=&quot;String&quot; Required=&quot;true&quot; Visible=&quot;true&quot; Source=&quot;false&quot; Lazy=&quot;false&quot;/&gt;&lt;/Variables&gt;&lt;Body Width=&quot;595&quot; Height=&quot;842&quot; Margin=&quot;20&quot;&gt;&lt;Variables/&gt;&lt;Header&gt;&lt;Text Binding=&quot;Constant&quot; Content=&quot;Simple Account report with account records names&quot; Style=&quot;H1&quot; Column=&quot;0&quot; Row=&quot;0&quot; ColSpan=&quot;1&quot; RowSpan=&quot;1&quot;/&gt;&lt;/Header&gt;&lt;Repeater Alias=&quot;account&quot; FetchVariable=&quot;src&quot;&gt;&lt;Variables/&gt;&lt;Header&gt;&lt;Text Binding=&quot;Constant&quot; Content=&quot;Account Name&quot; Style=&quot;Normal&quot; Column=&quot;0&quot; Row=&quot;0&quot; ColSpan=&quot;1&quot; RowSpan=&quot;1&quot;/&gt;&lt;/Header&gt;&lt;Grid&gt;&lt;Text Binding=&quot;Value&quot; Content=&quot;account.name&quot; Style=&quot;Normal&quot; Column=&quot;0&quot; Row=&quot;0&quot; ColSpan=&quot;1&quot; RowSpan=&quot;1&quot;/&gt;&lt;/Grid&gt;&lt;/Repeater&gt;&lt;Footer&gt;&lt;Text Binding=&quot;Constant&quot; Content=&quot;Martin Test&quot; Style=&quot;Normal&quot; Column=&quot;0&quot; Row=&quot;0&quot; ColSpan=&quot;1&quot; RowSpan=&quot;1&quot;/&gt;&lt;/Footer&gt;&lt;/Body&gt;&lt;/Report&gt;</Data>
  <EntityId>022e0024-35ca-41ba-a8cc-2f5ff304a919</EntityId>
  <GenerateReportFormat>Pdf</GenerateReportFormat>
  <Variables>
    <Variable name="name1">value1</Variable>
    <Variable name="name2">value2</Variable>
  </Variables>
</GenerateReportRequest>

Format possibilities

<GenerateReportFormat>Pdf</GenerateReportFormat>
<GenerateReportFormat>Html</GenerateReportFormat>
<GenerateReportFormat>Word</GenerateReportFormat>
<GenerateReportFormat>Excel</GenerateReportFormat>

Time zone

<TimeZoneOffset>-120</TimeZoneOffset>

POST ExecuteWorkflow

Allows you to start a server process.

Sample URL:

https://{organization}.app.resco.net/rest/v1/data/ExecuteWorkflow

Request:

<WorkflowExecuteRequest xmlns="http://schemas.resco.net/XRM/OrganizationService">
                <WorkflowReference>resco_workflow:C0A79A17-FDDD-4152-9B19-F24FAF7D8095</WorkflowReference>
                <PrimaryEntity Name="account">
                                <name>Entity name</name>
                                <country>XX</country>
                </PrimaryEntity>
                <PrimaryReference>account:56de02f2-732a-4020-837e-93561c70ad07</PrimaryReference>
                <InputVariables>
                                <Variable Name="Test1" Type="Integer" Value="50" />
                                <Variable Name="Test2" Type="String" Value="string" />
                                <Variable Name="Test3" Type="Float" Value="45.26" />
                                <Variable Name="Test4" Type="DateTme" Value="2021-18-01T16:09:53Z" />
                                <Variable Name="Test5" Type="Decimal" Value="65.26" />
                                <Variable Name="Test6" Type="BigInt" Value="156" />
                                <Variable Name="Test7" Type="Lookup" Value="contact:826191dc-2dea-47f7-9b38-616b22129d8b" />
                </InputVariables>
                <OutputVariables>
                                <Variable>Var1</Variable>
                                <Variable>Var2</Variable>
                </OutputVariables>
</WorkflowExecuteRequest>

• WorkflowReference - EntityReference to record in resco_workflow entity.

• PrimaryEntity - Determine the primary entity used in the workflow as the 'Entity' variable. It can be defined as a new Entity.

• PrimaryReference - Determine the primary entity used in the workflow as the 'Entity' variable. It can be defined as an EntityReference to an existing entity record.

• InputVariables - Determine input variables that can be used in the workflow.

• OutputVariables - Determine names of variables that should be returned from the workflow.

Result:

<WorkflowExecuteResult>
                <Result>Succeeded</Result>
                <Saved>true</Saved>
                <Log>Workflow log.</Log>
                <OutputVariables>
                                <Variable Name="Var1" Type="Integer" Value="100" />
                                <Variable Name="Var2" Type="String" Value="string + output" />
                </OutputVariables>
</WorkflowExecuteResult>

• Result - Determine the result status of the workflow (InProgress, Succeeded, Failed, Canceled).

• Saved - Determine whether the WorkflowExecuteRequest.PrimaryEntity was changed and updated after workflow execution.

• Log - Determine the result log printed by workflow.

• OutputVariables - Contains the output variables returned from the workflow.

Metadata service

This document describes the REST API of the Resco Cloud metadata service. It lets you read and change the data model (entities, attributes, option sets) and the localization labels of an organization. It is the metadata counterpart of the data service.

Base service namespace

http://schemas.resco.net/XRM/MetadataService

Base URL

The URL styles are the same as for the data service:

• Domain organization: https://{organization}.app.resco.net/rest/v1/metadata/...

• URL organization: https://{server}/rest/v1/metadata/{organization}/...

{database} in this document is the organization name. When the organization is already identified by the host name, the {database} segment can be left out: /rest/v1/metadata/account and /rest/v1/metadata/{organization}/account return the same result. Examples below show the short form where it works.

Authentication

• Requests use HTTP Basic authentication with the organization login, as in the data service: Authorization: Basic BASE64(login:password). Requests without credentials get HTTP 401.

• GET /$version and GET /{database}/$version are anonymous.

• Read endpoints return XML serialized from the metadata model.

• Write endpoints accept XML request bodies for complex types.

Content types and serialization

• Request and response bodies use XML serialization for complex types.

• Primitive responses are returned as one XML element, for example <string>...</string>, <dateTime>...</dateTime> or <ArrayOfInt><int>...</int></ArrayOfInt>. Create operations return <guid>; update and delete operations return <boolean>.

• ExecuteMetadata uses its own XML namespace: http://schemas.resco.net/XRM/Execute.

• Faults, when returned, use the XRM service error namespace.

Data namespaces

• Metadata namespace: http://schemas.resco.net/XRM/MetadataService

• Execute namespace: http://schemas.resco.net/XRM/Execute

• Fault namespace: http://schemas.resco.net/XRM/XRMServiceError

Quick endpoint summary

Rows marked ⚠ change the organization. All other endpoints are read-only.

XML object catalog

MetadataRoot

XML root: Metadata

Namespace: http://schemas.resco.net/XRM/MetadataService

Represents the full metadata document returned by Retrieve and accepted by UpdateMetadata.

Structure

• Organization element: organization-level metadata (Id attribute and, for example, a BaseTransactionCurrency child).

• Entities element: wrapper that contains one Entity element per entity definition in the database.

The full document is large (about 5 MB for an organization with several hundred entities). Prefer the single-entity endpoints when you only need part of it, and use $metadataversion to decide whether a cached copy is still current.

Example

<Metadata xmlns="http://schemas.resco.net/XRM/MetadataService">
  <Organization Id="00000000-0000-0000-0000-0000000000aa">
    <BaseTransactionCurrency Id="00000000-0000-0000-0000-0000000000bb" />
  </Organization>
  <Entities>
    <Entity Name="account" Id="00000000-0000-0000-0000-000000000001">
      <Attributes>
        <Attribute Name="name" Id="00000000-0000-0000-0000-000000000010" Type="String" />
      </Attributes>
    </Entity>
  </Entities>
</Metadata>

EntityMetadata

XML root: Entity

Namespace: http://schemas.resco.net/XRM/MetadataService

Represents one entity definition.

Common attributes

• Name - logical entity name.

• Id - entity identifier.

• OwnershipType - ownership model when present.

• EntityAttributes - bit flags describing entity behavior.

• EntityParent - parent entity name when applicable.

• ExternalName - external name when configured. For entities that mirror a Dynamics/Dataverse table this is a semicolon-separated value with four segments, for example 1;accountid;;accounts or 4200;activityid;subject;activitypointers. The first segment is the table's object type code, the second is the primary key attribute and the last is the collection name. The third segment is usually empty.

• PrimaryKeyName - logical name of the primary key attribute, when present.

• PrimaryFieldName - logical name of the attribute used as the record's display name, when present.

• IsAuditEnabled - true when changes to the entity are audited.

• EntityTypeCode - numeric type code when present.

• CustomerOwnershipField - ownership field name when present.

• Extensions - semicolon-separated markers set by the system, for example ms:dynamics, ms:noversionnumber, rc:rescocloud.

Description is returned as a child element (see below), not as an XML attribute.

Child elements

• Description - entity description when present.

• Attributes - wrapper that contains one Attribute element (AttributeMetadata) per attribute.

Example

<Entity xmlns="http://schemas.resco.net/XRM/MetadataService" Name="account" Id="00000000-0000-0000-0000-000000000001"
        OwnershipType="User" IsAuditEnabled="true" Extensions="ms:dynamics">
  <Description>Business that represents a customer or potential customer.</Description>
  <Attributes>
    <Attribute Name="name" Id="00000000-0000-0000-0000-000000000010" Type="String" Length="160" Required="true" />
    <Attribute Name="accountnumber" Id="00000000-0000-0000-0000-000000000011" Type="String" Length="20" />
  </Attributes>
</Entity>

AttributeMetadata

XML root: Attribute

Namespace: http://schemas.resco.net/XRM/MetadataService

Represents one attribute definition.

Common attributes

• Name - logical attribute name.

• Id - attribute identifier.

• EntityName - entity owner in execute payloads.

• Type - attribute type (see the list below).

• Length - maximum length for string-like attributes.

• Required - whether the attribute is required.

• System - whether the attribute is system-managed.

• Default - default value when present. For option sets this is the value of the default option; -1 is common and means that nothing is selected.

• Permissions - space-separated list of Read, Create, Update. An attribute without Create cannot be set when a record is created.

• OptionSetValues - valid values of an option set, see below.

• OptionSetTextValues - valid values of a text option set (string attribute that accepts only listed texts), semicolon-separated.

• Min, Max, Precision - limits and decimal places for numeric attributes.

• Format - format hint for string attributes, for example Text.

• Extensions - semicolon-separated markers set by the system, for example ms:dynamics.

• LookupTargets - lookup target list when applicable: semicolon-separated entity names (contact, or account;contact for a lookup that can point to several entities).

• LookupUpdateConstraint - constraint enforced when the record referenced by this lookup is about to change (re-targeted). Allowed values:

  • NoAction (default) - no check is performed.

  • Restrict - the operation fails with an error if the referenced target record no longer exists at the time of the check.

• LookupDeleteConstraint - constraint enforced when the record referenced by this lookup is deleted. Allowed values:

  • NoAction (default) - deleting the referenced record has no effect on records that reference it.

  • Restrict - deleting the referenced record fails with an error if any record still references it through this lookup.

  • Cascade - all records that reference the deleted record through this lookup are deleted as well.

  • RemoveLink - the lookup value (and its target type) is cleared (set to null) on all records that reference the deleted record, instead of deleting them.

• ExternalName - external name when configured.

• AllowOverwriteType - whether the type can be overwritten.

Child elements

• Description - attribute description when present.

Types

UniqueIdentifier, Boolean, String, Lookup, DateTime, Picklist, PicklistMap, RowVersion, Float, Integer, Money, Decimal, BigInt, Binary, File, PartyList.

Option sets (OptionSetValues)

For PicklistMap each pair is stateValue,statusValue: parentValue is the value of the entity's state attribute (for example statuscode's parent statecode), and value is the status (reason) option that is valid for that state.

The metadata contains the option values only. The display labels are in the localization (see RetrieveLocalization); the label of option 2 of account.industrycode has the key account.industrycode.2.

Example

<Attribute xmlns="http://schemas.resco.net/XRM/MetadataService" Name="industrycode" Id="00000000-0000-0000-0000-000000000010"
           Type="Picklist" Required="false" Default="-1" Permissions="Read Create Update" OptionSetValues="1;2;3;4;5">
  <Description>Select the account's primary industry.</Description>
</Attribute>
<Attribute xmlns="http://schemas.resco.net/XRM/MetadataService" Name="primarycontactid" Id="00000000-0000-0000-0000-000000000011"
           Type="Lookup" Required="false" LookupTargets="contact" Permissions="Read Create Update" />

DisplayName

XML root: DisplayName

Used inside localization languages.

Attributes / content

• Name - localization key.

• text value - localized label.

Localization keys

Example

<DisplayName Name="account">Account</DisplayName>
<DisplayName Name="account.industrycode.2">Agriculture and Non-petrol Natural Resource Extraction</DisplayName>

DisplayNameCollection

XML root: Language

Namespace: http://schemas.resco.net/XRM/MetadataService

Represents one localization language.

Attributes

• LCID - language identifier.

Child elements

• DisplayName - localized labels.

Example

<Language xmlns="http://schemas.resco.net/XRM/MetadataService" LCID="1033">
  <DisplayName Name="account">Account</DisplayName>
  <DisplayName Name="account+s">Accounts</DisplayName>
</Language>

LocalizationDataCollection

XML root: Localization

Namespace: http://schemas.resco.net/XRM/MetadataService

Represents the full localization set.

Child elements

• Language - one entry per LCID.

Example

<Localization xmlns="http://schemas.resco.net/XRM/MetadataService">
  <Language LCID="1033">
    <DisplayName Name="account">Account</DisplayName>
  </Language>
  <Language LCID="1051">
    <DisplayName Name="account">Obchodny vztah</DisplayName>
  </Language>
</Localization>

ExecuteMetadata

XML root: ExecuteMetadata

Namespace: http://schemas.resco.net/XRM/Execute

Represents a batch of metadata operations executed in one request.

Attributes

• ContinueOnError - continue after a failed item when true.

• TransactionType - transaction behavior for the batch.

Child elements

• Entity - ExecuteEntityMetadata

• Attribute - ExecuteAttributeMetadata

• Localization - ExecuteLocalizationMetadata

Example

<ExecuteMetadata xmlns="http://schemas.resco.net/XRM/Execute" ContinueOnError="true" TransactionType="RollbackOnError">
  <Entity Action="Create" Name="new_entity" />
  <Attribute Action="Update" EntityName="account" Name="name" Id="00000000-0000-0000-0000-000000000010" Type="String" Length="160" />
  <Localization LCID="1033">
    <DisplayName Key="account" Label="Account" />
  </Localization>
</ExecuteMetadata>

ExecuteEntityMetadata

XML root: Entity

Namespace: http://schemas.resco.net/XRM/Execute

Extends entity metadata with an execute action.

Attributes

• Action - operation to execute: Create, Update, Upsert, or Delete.

• Other entity attributes follow the metadata entity model.

Example

<Entity xmlns="http://schemas.resco.net/XRM/Execute" Action="Create" Name="new_entity" />

ExecuteAttributeMetadata

XML root: Attribute

Namespace: http://schemas.resco.net/XRM/Execute

Extends attribute metadata with the owning entity name and an execute action.

Attributes

• EntityName - owning entity logical name.

• Action - operation to execute: Create, Update, Upsert, or Delete.

Example

<Attribute xmlns="http://schemas.resco.net/XRM/Execute" Action="Update" EntityName="account" Name="name"
           Id="00000000-0000-0000-0000-000000000010" Type="String" Length="160" />

ExecuteLocalizationMetadata

XML root: Localization

Namespace: http://schemas.resco.net/XRM/Execute

Represents one localization update inside an execute batch.

Attributes

• LCID - language identifier.

Child elements

• DisplayName - one or more key/label pairs.

Example

<Localization xmlns="http://schemas.resco.net/XRM/Execute" LCID="1033">
  <DisplayName Key="account" Label="Account" />
  <DisplayName Key="account+s" Label="Accounts" />
</Localization>

ExecuteLocalizationDisplayName

XML root: DisplayName

Namespace: http://schemas.resco.net/XRM/Execute

Represents one key/label pair in an execute localization batch.

Attributes

• Key - localization key.

• Label - localized text.

Example

<DisplayName Key="account" Label="Account" />

ExecuteResponse

XML root: Response

Namespace: http://schemas.resco.net/XRM/Execute

Represents the outcome of one item in an execute batch.

Attributes / elements

• Action - action that was processed.

• Result - successful result payload.

• Fault - fault payload when the operation fails.

Example

<Response Action="Create">
  <Result Type="guid">2f7a8df0-6b7f-4b15-9da0-3c2fd8b1a6f1</Result>
</Response>

ExecuteResult

XML root: Result

Namespace: http://schemas.resco.net/XRM/Execute

Represents the result value of one execute item.

Attributes / content

• Type - result kind: guid, bool, or array.

• text value - the serialized result when Type is guid or bool.

• Value child elements - used when Type is array.

Examples

<Result Type="guid">2f7a8df0-6b7f-4b15-9da0-3c2fd8b1a6f1</Result>
<Result Type="bool">true</Result>
<Result Type="array">
  <Value Name="id">00000000-0000-0000-0000-000000000001</Value>
</Result>

ExecuteResultValue

XML root: Value

Namespace: http://schemas.resco.net/XRM/Execute

Represents a named value inside an array result.

Attributes / content

• Name - value name.

• text value - value content.

Example

<Value Name="id">00000000-0000-0000-0000-000000000001</Value>

ExecuteMultipleResponse

XML root: MultipleResponse

Namespace: http://schemas.resco.net/XRM/Execute

Represents a list of ExecuteResponse items.

Example

<MultipleResponse xmlns="http://schemas.resco.net/XRM/Execute">
  <Response Action="Create">
    <Result Type="guid">2f7a8df0-6b7f-4b15-9da0-3c2fd8b1a6f1</Result>
  </Response>
  <Response Action="Update">
    <Result Type="bool">true</Result>
  </Response>
</MultipleResponse>

Detailed operations

GetVersion

Returns the server version string used by the service host. This endpoint is anonymous and is typically used for health checks, client compatibility detection, and installation diagnostics.

Request

GET /$version

Response

<string>RescoXRMServer:12.4.0-18.11:Enterprise:Resco Cloud</string>

GetServerVersion

Returns the same version string as GetVersion, but scoped to a database path. The current implementation ignores the database argument and returns the host version.

Request

GET /sample/$version

Response

<string>RescoXRMServer:12.4.0-18.11:Enterprise:Resco Cloud</string>

GetMetadataVersion

Returns the last metadata change timestamp for the selected database. Clients can cache metadata and poll this endpoint to determine whether a refresh is needed.

Request

GET /sample/$metadataversion

Response

<dateTime>2024-02-29T15:41:23</dateTime>

Retrieve

Returns the full metadata document for the database. The payload contains organization data and the full entity tree. Use this endpoint when a client needs a complete refresh of its metadata cache.

Request

GET /sample

Response

<Metadata xmlns="http://schemas.resco.net/XRM/MetadataService">
  <Organization Id="00000000-0000-0000-0000-0000000000aa">
    <BaseTransactionCurrency Id="00000000-0000-0000-0000-0000000000bb" />
  </Organization>
  <Entities>
    <Entity Name="account" Id="00000000-0000-0000-0000-000000000001">
      <Attributes>
        <Attribute Name="name" Id="00000000-0000-0000-0000-000000000010" Type="String" />
      </Attributes>
    </Entity>
  </Entities>
</Metadata>

RetrieveEntities

Returns all entity definitions for the database. The filter query parameter can be used to reduce the returned set when the server supports filtering. The response is a collection of Entity elements serialized with the metadata namespace.

Request

GET /sample/$entities?filter=All

Response

<Entities xmlns="http://schemas.resco.net/XRM/MetadataService">
  <Entity Name="account" Id="00000000-0000-0000-0000-000000000001">
    <Attributes>
      <Attribute Name="name" Id="00000000-0000-0000-0000-000000000010" Type="String" />
    </Attributes>
  </Entity>
  <Entity Name="contact" Id="00000000-0000-0000-0000-000000000002" />
</Entities>

filter is a flags enumeration (MetadataFilter) with the values None, Entity, Attributes and All (All = Entity | Attributes). Use All to get entities together with their attributes; Entity returns only the entity-level fields without the Attributes wrapper.

RetrieveEntity

Returns one entity definition by logical name. Use this endpoint when you only need a single entity instead of the whole database metadata set.

Request

GET /sample/account?filter=All

Response

<Entity xmlns="http://schemas.resco.net/XRM/MetadataService" Name="account" Id="00000000-0000-0000-0000-000000000001">
  <Description>Business that represents a customer or potential customer.</Description>
  <Attributes>
    <Attribute Name="name" Id="00000000-0000-0000-0000-000000000010" Type="String" Length="160" Required="true" />
  </Attributes>
</Entity>

RetrieveAttributes

Returns all attributes for one entity. The response is a collection of Attribute elements. This endpoint is useful when a client already knows the entity and only needs field metadata.

Request

GET /sample/account/$attributes

Response

<Attributes xmlns="http://schemas.resco.net/XRM/MetadataService">
  <Attribute Name="name" Id="00000000-0000-0000-0000-000000000010" Type="String" Length="160" Required="true" />
  <Attribute Name="accountnumber" Id="00000000-0000-0000-0000-000000000011" Type="String" Length="20" />
</Attributes>

RetrieveAttribute

Returns one attribute definition by entity name and attribute name. Use this endpoint for targeted lookups when only a single field definition is needed.

Request

GET /sample/account/name

Response

<Attribute xmlns="http://schemas.resco.net/XRM/MetadataService" Name="name" Id="00000000-0000-0000-0000-000000000010"
           Type="String" Length="160" Required="true" Permissions="Read Create Update" />

RetrieveLocalizations

Returns the full localization set for the database. The response contains one language node per LCID, and each language contains key/label pairs for entity, attribute, and option labels.

The full set contains every installed language and is large. To read the labels of one language use $localizations?lcid={lcid} (next operation).

Request

GET /sample/$localizations

Response

<Localization xmlns="http://schemas.resco.net/XRM/MetadataService">
  <Language LCID="1033">
    <DisplayName Name="account">Account</DisplayName>
    <DisplayName Name="account+s">Accounts</DisplayName>
  </Language>
  <Language LCID="1051">
    <DisplayName Name="account">Obchodny vztah</DisplayName>
    <DisplayName Name="account+s">Obchodne vztahy</DisplayName>
  </Language>
</Localization>

RetrieveLocalization

Returns one localization language by LCID. This is the targeted version of RetrieveLocalizations and is useful when a client only needs one language. It is also where the labels of option-set values come from: the metadata gives the values (OptionSetValues) and this endpoint gives their labels ({entity}.{attribute}.{value} keys). An organization with several hundred entities returns about 2.5 MB per language, so cache the result and refresh it when $metadataversion changes.

Request

GET /sample/$localizations?lcid=1033

Response

<Language LCID="1033" xmlns="http://schemas.resco.net/XRM/MetadataService">
  <DisplayName Name="account">Account</DisplayName>
  <DisplayName Name="account+s">Accounts</DisplayName>
  <DisplayName Name="account.name">Account Name</DisplayName>
  <DisplayName Name="account.industrycode.2">Agriculture and Non-petrol Natural Resource Extraction</DisplayName>
</Language>

GetAvailableLocalizations

Returns the list of LCIDs that are currently available for the database. This endpoint is useful for populating language selectors before fetching specific localization payloads.

Request

GET /sample/$availablelocalizations

Response

<ArrayOfInt>
  <int>1033</int>
  <int>1051</int>
</ArrayOfInt>

UpdateMetadata

Replaces or updates the full metadata document for a database. Use this endpoint when you want to submit a metadata tree that contains one or more entity and attribute changes in a single request.

Request

POST /sample

<Metadata xmlns="http://schemas.resco.net/XRM/MetadataService">
  <Entity Name="account">
    <Attribute Name="new_customtext" />
  </Entity>
</Metadata>

Response

true

CreateEntity

Creates a new entity definition in the target database. The request body is a single Entity document in the metadata namespace.

Request

POST /sample/$create

<Entity xmlns="http://schemas.resco.net/XRM/MetadataService" Name="new_entity" />

Response

<guid>2f7a8df0-6b7f-4b15-9da0-3c2fd8b1a6f1</guid>

The new entity is created with the standard system attributes (id, name, createdon, createdby, ...) and can be used immediately through the data service and OData. Creating an entity whose name already exists fails with HTTP 500 (Specified entity 'new_entity' already exist!). The call increases $metadataversion.

UpdateEntity

Updates an existing entity definition. The request body contains the entity identifier (Id) and the entity name. Not every entity property can be changed through this call.

Request

POST /sample/$update

<Entity xmlns="http://schemas.resco.net/XRM/MetadataService" Name="account" Id="00000000-0000-0000-0000-000000000001" />

Response

<boolean>true</boolean>

DeleteEntity

Deletes an entity definition identified by its logical name. No XML body is required. Afterwards the entity is no longer returned by the metadata service, and the data service rejects it.

This is a destructive operation. Deleting an entity permanently removes it together with all of its records; there is no "soft delete" or way to recover the data afterwards. Attributes do not need to be deleted first - deleting the entity removes its attributes and all of its data in the same call. The server blocks deletion only when the entity is a system entity or when another entity still has a lookup attribute pointing at it; it does not check whether the entity holds any records.

Request

GET /sample/$delete?entity=new_entity

Response

<boolean>true</boolean>

CreateAttribute

Creates a new attribute under the specified entity. The request body is a single Attribute document in the metadata namespace.

Request

POST /sample/$createAttribute?entity=account

<Attribute xmlns="http://schemas.resco.net/XRM/MetadataService" Name="new_customtext" Type="String" Length="100" />

For a picklist, add the valid values: Type="Picklist" OptionSetValues="1;2;3" Default="-1". A new attribute gets Permissions="Read Create Update" unless you set it otherwise.

Response

<guid>7e1f7a37-5bcf-4d9e-b4c5-b9fd1d1c3d42</guid>

UpdateAttribute

Updates an existing attribute under the specified entity. Include the entity context in the query string and the attribute definition in the body.

Request

POST /sample/$updateAttribute?entity=account

<Attribute xmlns="http://schemas.resco.net/XRM/MetadataService" Name="new_customtext" Id="00000000-0000-0000-0000-000000000011"
           Type="String" Length="150">
  <Description>Customer note</Description>
</Attribute>

The attribute is found by Id. A request without the id of an existing attribute fails with HTTP 500 (Entity contains no matching attribute with id). Read the current definition first and send it back with your changes.

Response

<boolean>true</boolean>

DeleteAttribute

Deletes one attribute from the specified entity. No XML body is required.

Request

GET /sample/$deleteAttribute?entity=account&attribute=new_customtext

Response

<boolean>true</boolean>

ExecuteMetadata

Executes a mixed batch of metadata operations in one request. This endpoint is the most flexible option when you need to create, update, delete, or localize multiple metadata items together.

Request

POST /sample/$execute

<ExecuteMetadata xmlns="http://schemas.resco.net/XRM/Execute" ContinueOnError="true" TransactionType="None">
  <Attribute Action="Create" EntityName="new_entity" Name="new_a" Type="String" Length="20" />
  <Attribute Action="Update" EntityName="new_entity" Name="missing" Type="String" Length="5" />
  <Attribute Action="Create" EntityName="new_entity" Name="new_c" Type="String" Length="20" />
</ExecuteMetadata>

(Other item types are Entity and Localization, as in the object catalog above. The localization item is not covered by the tested examples.)

Response

The HTTP status is 200 even when an item fails. The failed item is reported as a Fault inside its Response:

<MultipleResponse xmlns="http://schemas.resco.net/XRM/Execute">
  <Response Action="Create">
    <Result Type="guid">2f7a8df0-6b7f-4b15-9da0-3c2fd8b1a6f1</Result>
  </Response>
  <Response Action="Update">
    <Fault xmlns="http://schemas.resco.net/XRM/XRMServiceError">
      <Code>500</Code>
      <Reason>InvalidOperationException</Reason>
      <Message>Unable to update attribute: Entity contains no matching attribute with id!</Message>
      <Detail>...</Detail>
    </Fault>
  </Response>
  <Response Action="Create">
    <Result Type="guid">7e1f7a37-5bcf-4d9e-b4c5-b9fd1d1c3d42</Result>
  </Response>
</MultipleResponse>

Transactions

• TransactionType="None" with ContinueOnError="true": every item that can succeed is applied; failed items are reported in their Response.

• TransactionType="RollbackOnError" with ContinueOnError="false": nothing is applied when an item fails. The response still lists the earlier items as successful (Result), so check for a Fault in any item before assuming the changes were kept.

• An Update item must identify the attribute by Id (see UpdateAttribute).

Examples

All examples use Basic authentication (Authorization: Basic BASE64(login:password)).

List the valid values of a picklist, with labels

GET /rest/v1/metadata/account/industrycode

The OptionSetValues attribute lists the values (1;2;3;...). Request GET /rest/v1/metadata/$localizations?lcid=1033 and look up the keys account.industrycode.1, account.industrycode.2, ... for the labels.

Find out which fields can be set when creating a record

GET /rest/v1/metadata/account/$attributes

Use the attributes whose Permissions contain Create. Required="true" marks the ones that must be provided (some system-filled attributes, such as the record id and owner, are marked as required but are set by the server).

Refresh a metadata cache only when needed

GET /rest/v1/metadata/$metadataversion

Store the returned timestamp together with your cached metadata and load the metadata again only when it changes.

Behavior notes

• filter is an optional metadata filter used by retrieval endpoints.

• ContinueOnError controls whether batch execution continues after a failed item.

• TransactionType="RollbackOnError" rolls back the batch if any item fails.

• ExecuteResponse can include a fault in the XRM fault namespace when an item fails.

• The {database} path segment is optional when the organization is identified by the host name.

• A failed item in $execute is reported as a Fault inside its Response element; the HTTP status of the request is 200.

• A failed single call (for example $create of an existing entity, an invalid Type, or malformed XML) returns HTTP 500 with a Fault body that contains Code, Reason, Message and Detail.

• Every successful write increases the value returned by $metadataversion.

• Examples were checked against a development organization; an entity created, changed and deleted through these endpoints was usable through the data service and OData immediately after creation.

Asynchronous operations

All operations with "Multiple" in their names support asynchronous execution. Use the Prefer header to instruct the server to use async operations:

Prefer: respond-async
Prefer: respond-async, wait=10

The wait HTTP preference is optional. It indicates the maximum duration the client is willing to wait for a response. The default value is 20 seconds.

The server returns "200 OK" when completed within the wait time or "202 Accepted" when not.

To poll the current status of the async operation, execute the "Multiple" method with an empty body and $ticket={ticket} query string, where the {ticket} is returned with the first request "202 Accepted".

There is a response header "Progress" with the progress of the async operation.

Webhooks

Resco Cloud REST API supports webhooks. A create, update, or delete operation on the server can trigger a callback to a URL of your choosing.

CreateWebhook: /$hook?$entity={entity}&$action={action}

• entity: entity name

• action: one of [Create | Update | Delete]

• POST BODY: <Url><CallbackUrl>URL to invoke</CallbackUrl></Url>

• RESPONSE HEADER: Location: URL to delete webhook

The BODY of the request to the external URL is in JSON format: '{ "id": "record id" }'

Sample C# project

For your convenience, we have prepared a C# project that implements the data service.

• https://app.resco.net/docs/RescoCRM.SDK.zip - source code for Visual Studio

• https://www.nuget.org/packages/Resco.Cloud.Client/ - library with regular updates

See also

Resco also offers you a development kit that allows you to develop your own plugins for Resco Cloud. Plugins can be used in processes:

• RescoCRM Plugin SDK

Last updated: October 01, 2026