Obtaining Master data from a Table

We need to obtain the list of countries defined on the FM System.

We will suppose that:

Public API Key is MY_PUBLIC_API_KEY.
Private API Key is MY_PRIVATE_API_KEY.
The current date is: 09/15/2014 @ 06:30:00 UTC; which means the Unix Timestamp is: 1410762600.
With the previous values, the message signature is:Signature=
sha1(1410762600MY_PUBLIC_API_KEYMY_PRIVATE_API_KEY)Signature=ade34d48ae061b478dd3de6f958dd572af575050

Step 1: Perform a GET call for Obtaining the List of Available Resources

1 2	curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410762600" -H "X-FM-Signature: ade34d48ae061b478dd3de6f958dd572af575050" https://restfm.forcemanager.net/api/values/info

Then, we get the result:

[

{

"Name": "tblEstadoExpediente",

"Description": "Expedient status"

{

"Name": "tblcountries",

"Description": "Countries List"

…

{

"Name": "Z_Table_1",

"Description": "Z_Table_1 description"

…

{

"Name": "Z_Table_N",

"Description": "Z_Table_N description"

}

]

So, as we can see, tblcountries is the resource we are looking for, this is because it’s the definition of countries on the system.

Step 2: Perform a GET to obtain call Search List of Values by Resource Name

1 2	curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410762600" -H "X-FM-Signature: ade34d48ae061b478dd3de6f958dd572af575050" https://restfm.forcemanager.net/api/values?resourceName=tblCountries

Then, we get the data:

[

{

"created_date": "2012-01-10T19:06:30",

"modified_date": "2012-01-10T19:06:30",

"id": "240",

"intISONUM": "716",

"strISO2": "ZW",

"strISO3": "ZWE",

"strName": "Zimbabue",

"strname_DE": "",

"strname_EN": "Zimbabwe",

"strname_FR": "",

"strname_IT": "",

"strname_PT": "",

"strname_US": ""

{

"created_date": "2012-01-10T19:06:30",

"modified_date": "2012-01-10T19:06:30",

"id": "239",

"intISONUM": "894",

"strISO2": "ZM",

"strISO3": "ZMB",

"strName": "Zambia",

"strname_DE": "",

"strname_EN": "Zambia",

"strname_FR": "",

"strname_IT": "",

"strname_PT": "",

"strname_US": ""

…

]

Remember this list is paginated, in this case there are no other pages; but if this the case you should use the pagination headers to get more data as shown in the Pagination example.

Company update

We want to update a company, the one with id 5000.

We will suppose that:

Public API Key is MY_PUBLIC_API_KEY.
Private API Key is MY_PRIVATE_API_KEY.
The current date is: 09/15/2014 @ 06:30:00 UTC; which means the Unix Timestamp is: 1410762600.
With the previous values, the message signature is: Signature = sha1(1410762600MY_PUBLIC_API_KEYMY_PRIVATE_API_KEY) Signatureade34d48ae061b478dd3de6f958dd572af575050

Step 1: Perform a GET and obtain the input format.

1 2	curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410762600" -H "X-FM-Signature: ade34d48ae061b478dd3de6f958dd572af575050" https://restfm.forcemanager.net/api/companies/5000

Them, we get the formatted data:

[

{

"id": "5000",

"name": "Test Company",

"address_1": "Company address 1",

"address_2": "Company address 2",

"geocode_longitude": "2.094477",

"geocode_latitude": "41.379681",

"city_name": "Barcelona",

"province_name": "Barcelona",

"postcode": "08950",

"phone": "9357454646",

"phone_2": "",

"mobile_phone": "",

"fax": "",

"comment": "",

"email": "mail@test.com",

"website": "www.test.com",

"segment_id": "1",

"sales_rep_id": "600",

"sales_rep_2_id": "124",

"sales_rep_3_id": "351",

"sales_rep_4_id": "",

"sales_rep_5_id": "",

"account_type_id": "21",

"country_id": "73",

"modified_date": "2014-05-24T11:47:57",

"permission_level": "2",

"geocoded": "True",

"visible_to_all": "",

"created_date": "2014-05-22T10:27:21",

"z_external_text ": "JAPAN-981"

}

]

So, as you may have noticed there are some fields that are ids. If you want to modify the company’s owner (sales_rep_id), you should know the id of the new one.

Step 2: Getting missing ids

To get the missing sales_rep_id you need to obtain its id first on your system, so if in your system such person has the id = 123, we can then search for it on FM.

Current Unix Timestamp is: 1410762720
Signature = 39e7a01ea386e157cb936942d242f8d071e30ede

curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410762720"

-H "X-FM-Signature: ade34d48ae061b478dd3de6f958dd572af575050"

“https://restfm.forcemanager.net/FM_Restful_API/api/internalid?type=user&externalId=123”

You would get the response if found:

1	[ { "Id": "875" } ]

Then, we know now that this person has the id 875 in FM.

Step 3: Editing the request body

We want to:

Change the company’s owner.
Remove the 3rd sales representative.
Change the phone number.

Using cURL, the easiest option to specify the request body is to create a text file with a regular text editor and attach it on the call, we’ve seen this procedure on several points before.

Using a text editor, copy the returned response of Step 1 and paste it on a blank file, and only maintain those fields to be modified:

{

"phone": "934591234",

"sales_rep_id": "875",

"sales_rep_3_id": "",

"z_external_text ": "JAPAN-100"

}

You will notice that the response returns also a couple of external brackets ( [] ) that were remove, this is due the API returns list of objects and we only want to update one, in JSON these items represents the list, so we should exclude them from the file.

Save the file, in this case we will suppose the file is located on C:\temp\change_company_5000.json

Step 4: Updating the company on FM

To perform the update, we should perform an HTTP PUT call.

Current Unix Timestamp is: 1410762900.
Signature = 5a3dfcd16c2ad8e30d49bd51e920120ca802ff7c

1 2	curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410762900" -H "X-FM-Signature: 5a3dfcd16c2ad8e30d49bd51e920120ca802ff7c" -X PUT --data "@C:\temp\change_company_5000.json" https://restfm.forcemanager.net/api/companies

Then, the system responds with an HTTP 200 message and with the description “Entity updated successfully”.

Pagination

We want to get the list of all companies. We will suppose that:

Public API Key is MY_PUBLIC_API_KEY.
Private API Key is MY_PRIVATE_API_KEY.
The current date is: 09/15/2014 @ 06:30:00 UTC; which means the Unix Timestamp is: 1410762600.
With the previous values, the message signature is: Signature = sha1(1410762600MY_PUBLIC_API_KEYMY_PRIVATE_API_KEY) Signature =ade34d48ae061b478dd3de6f958dd572af575050

Step 1: Perform a GET method to obtain the data

1 2	curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410762600" -H "X-FM-Signature: ade34d48ae061b478dd3de6f958dd572af575050" https://restfm.forcemanager.net/api/companies

Then we get a list of values. For obvious reasons, we can’t put all the results here, we will show only the first record:

[

{

"id": "5000",

"name": "Test Company",

"address_1": "Company address 1",

"address_2": "Company address 2",

"geocode_longitude": "2.094477",

"geocode_latitude": "41.379681",

"city_name": "Barcelona",

"province_name": "Barcelona",

"postcode": "08950",

"phone": "9357454646",

"phone_2": "",

"mobile_phone": "",

"fax": "",

"comment": "",

"email": "mail@test.com",

"website": "www.test.com",

"segment_id": "1",

"sales_rep_id": "600",

"sales_rep_2_id": "124",

"sales_rep_3_id": "351",

"sales_rep_4_id": "",

"sales_rep_5_id": "",

"account_type_id": "21",

"country_id": "73",

"modified_date": "2014-07-11T11:47:57",

"permission_level": "2",

"geocoded": "True",

"visible_to_all": "",

"created_date": "2014-07-10T11:12:34",

"z_external_text ": "JAPAN-100"

}

{} /* 499 more records: 500 in total (500 is the pagesize) */

{}

……

]

The important thing in this example, is the response headers, we got:

X-FM-Entity-Count: 500

X-FM-Next-Page: 1

X-FM-Page: 0

X-FM-Prev-Page: 0

Then, as we receive data on the response body, there are probably more pages on this query. We can then could proceed with another request.

Step 2: Perform a GET method to obtain the data for the next page

The request is almost the same as the one on the first step, though we need to include the page header with the X-FM-Next-Page from the previous response:

curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410762600"

-H "X-FM-Signature: ade34d48ae061b478dd3de6f958dd572af575050" -H "X-FM-Page: 1"

https://restfm.forcemanager.net/api/companies

Then, again we get more data:

[

{

"id": "3400",

"name": "Test Company 2",

"address_1": "Company address 5",

"address_2": "Company address 6",

"geocode_longitude": "2.013477",

"geocode_latitude": "40.389681",

"city_name": "London",

"province_name": "London",

"postcode": "N160AN",

"phone": "020 8880 6111",

"phone_2": "",

"mobile_phone": "",

"fax": "",

"comment": "",

"email": "mail@test.com",

"website": "www.build.com",

"segment_id": "2",

"sales_rep_id": "300",

"sales_rep_2_id": "",

"sales_rep_3_id": "",

"sales_rep_4_id": "",

"sales_rep_5_id": "",

"account_type_id": "20",

"country_id": "73",

"modified_date": "2014-06-11T16:54:32",

"permission_level": "2",

"geocoded": "True",

"visible_to_all": "",

"created_date": "2013-08-11T11:56:55"

}

{} /* 11 more records: 12 in total */

{}

…

]

The response headers are:

X-FM-Entity-Count: 12

X-FM-Next-Page: 1

X-FM-Page: 1

X-FM-Prev-Page: 0

In this case, you will see the entity count is less than 500 and also X-FM-Next-Page = X-FM-Page, so, we are at the end of the data, however we will complete another request just to be sure.

Step 3: Perform a GET method to obtain the data for the next page

We do:

curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410762600"

-H "X-FM-Signature: ade34d48ae061b478dd3de6f958dd572af575050" -H "X-FM-Page: 2"

https://restfm.forcemanager.net/api/companies

Then we get and empty list in the response’s body:

[

{}

]

And the returned headers are:

X-FM-Entity-Count: 0

X-FM-Next-Page: 2

X-FM-Page: 2

X-FM-Prev-Page: 0

Then, we definitively don’t have any more data associated with this query.

Editing List of Values

We will create, update and delete a value from a Z_ table. We will suppose that:

The Z_ table is called: Z_Test.
Public API Key is MY_PUBLIC_API_KEY.
Private API Key is MY_PRIVATE_API_KEY.

IMPORTANT: Steps 1 and 2 are optional, they are shown in this document for clarifying purposes.

Step 1: Verify the table exists on the System

To perform this action, we will follow the procedure presented on the section: Obtaining Master data from a Table – Step 1: Perform a GET call for Obtaining the List of Available Resources

Then, we obtain the data and are able to see if the table exists:

[

{

"Name": "tblclevel1",

"Description": "Product category 1 (tblclevel2's parent)"

{

"Name": "tblclevel2",

"Description": "Product category 2 (tblclevel3's parent)"

...

{

"Name": "Z_Test",

"Description": "Z test table"

...

]

Step 2: Verify the table has the correct format

The idea is to gather some data from this value to see if it has the basic format as defined in: Performing operations on Lists of Values

Following the procedure Obtaining Master data from a Table – Step 2: Perform a GET to obtain call Search List of Values by Resource Name, but using ResourceName=Z_Test will fulfill this objective.

[

{

"deleted": "false",

"description_es": "Pizarra blanca 80x40 cm",

"description_de": "",

"description_en": "Whiteboard 80x40 cm",

"description_fr": " ",

"description_it": "",

"description_pt": "",

"deleted_date": "",

"created_date": "2014-05-23T11:26:19",

"modified_date": "2014-05-28T16:21:34",

"id": "5",

"intOrder": "1",

"strIdEnvironment": "10"

...

]

As you may have noticed, this resource has the required format to be operated as a Value.

Step 3: Inserting a value

We want to create a record on Z_Test, for this, we will send a JSON file with the data, the best option is to copy the result from the previous step, paste it on a text editor and modify the fields.

Save the file, in this case we will suppose the file is located on C:\temp\Create_Z_Record.json

Remember, some fields are read-only, and as such we are not able to pass them.

{

"resourceName": "Z_Test",

"data":

{

"description_es": "Pizarra blanca 80x40 cm",

"description_en": "Whiteboard 80x40 cm",

"intOrder": "1",

"strIdEnvironment": "99"

}

To perform the insert, we should perform an HTTP POST call.

Current Unix Timestamp is: 1410762900.
Signature = 5a3dfcd16c2ad8e30d49bd51e920120ca802ff7c

curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410762900"

-H "X-FM-Signature: 5a3dfcd16c2ad8e30d49bd51e920120ca802ff7c" -X POST --data "@C:\temp\Create_Z_Record.json"

https://restfm.forcemanager.net/api/values

Then, the system responds with an HTTP 201 message and a JSON object with the entity’s Id (in this case we suppose the id = 7) and the description “Entity created successfully with id: 7”.

Step 4: Updating a value

We will update the value inserted on the previous step, the id is 7. We want to:

Add the description in Italian language.
Remove the default description.
Change the strIdEnvironment to 45.

It is required to provide a JSON file with the changes, the same method we used before is also valid for this step. We will save the file on C:\temp\Update_Z_Record.json:

{

"resourceName": "Z_Test",

"data":

{

"description_es": "",

"description_it": "Lavagna bianca 80x40 cm",

"strIdEnvironment": "45"

}

To perform the update, we should perform an HTTP PUT call.

Current Unix Timestamp is: 1410763900.
Signature = 5a3dfcd16c2ad8e30d49bd51e110120ca802ff7c
Value id: 7

curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410763900"

-H "X-FM-Signature: 5a3dfcd16c2ad8e30d49bd51e110120ca802ff7c" -X PUT --data "@C:\temp\Update_Z_Record.json"

https://restfm.forcemanager.net/api/values/7

Then, the system responds with an HTTP 200 message and with the description “Entity updated successfully”.

Step 5: Deleting a value

We will delete the same record we have been working with. It is required to provide a JSON file with the resourceName. We will save the file on C:\temp\Delete_Z_Record.json:

{

"resourceName": "Z_Test"

}

To perform the delete, we should perform an HTTP DELETE call.

Current Unix Timestamp is: 1410764900.
Signature = 5a3dfcd16c2ad8e30d49bd51e110121da802ff7c
Value id: 7

curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1410764900"

-H "X-FM-Signature: 5a3dfcd16c2ad8e30d49bd51e110121da802ff7c " -X DELETE --data "@C:\temp\Delete_Z_Record.json"

https://restfm.forcemanager.net/api/values/7

Then, the system responds with an HTTP 200 with the body: “Entity deleted successfully”.

Related Entities: Searching and deleting Documents for Activities

We want to delete one of the documents related to an activity, the one with id 5384.

We will suppose that:

Public API Key is MY_PUBLIC_API_KEY.
Private API Key is MY_PRIVATE_API_KEY.
The current date is: 08/14/2015 @ 7:45:13 UTC; which means the Unix Timestamp is: 1439538313.
With the previous values, the message signature is: Signature = sha1(1439538313MY_PUBLIC_API_KEYMY_PRIVATE_API_KEY) Signature =f00b51e046c7e79a8ea3bbdeff13b904becd9169

Step 1: Perform a GET and obtain the list of documents

1 2	curl -H "Accept: application/json" -H "X-FM-PublicKey: MY_PUBLIC_API_KEY” -H "X-FM-UnixTimestamp: 1439538313" -H "X-FM-Signature: f00b51e046c7e79a8ea3bbdeff13b904becd9169" https://restfm.forcemanager.net/api/activities/5384/documents

Then we get the list of activity’s documents:

[

{

"Id": "11626",

"Name": "0011626.zip",

"URL": "https://fmdownload.s3/0011626.zip? AWSAccessKeyId=AK27J4EMMA&Expires=1439560663&Signature=TcCZG4dNb"

{

"Id": "11627",

"Name": "0011627.jpg",

"URL": "https://fmdownload.s3/0011627.jpg?AWSAccessKeyId=AK27J4EMMA&Expires=1439560664&Signature=bKYmn%2bN"

}

]

So, this activity has two documents, a zip with id: 11626 and a jpg with id: 11627. The field URL contains the link to download the file.

For security reasons, this links expires after several hours, then, it’s mean to be consumed in a short/medium period of time. The idea is to use your language libraries for performing this task, though is completely feasible to use a well know standard tool like wget.