Annex I. Examples

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

Then, we get as result:

 

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

Then, we get the data:

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) Signature =ade34d48ae061b478dd3de6f958dd572af575050

 

 

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

Them, we get the formatted data:

So, as you may 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

  

You would get the response if found:

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 that are  to be modified:

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

 

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 

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:

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:

Then, again we get more data:

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:

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 TableStep 1: Perform a GET call for Obtaining the List of Available Resources

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

 

 

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 TableStep 2: Perform a GET to obtain call Search List of Values by Resource Name, but using ResourceName=Z_Test will fulfill this objective.

As you may have noticed, this resource has the required format to be 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.

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

  • Current Unix Timestamp is: 1410762900.
  • Signature = 5a3dfcd16c2ad8e30d49bd51e920120ca802ff7c

 

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:

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

  • Current Unix Timestamp is: 1410763900.
  • Signature = 5a3dfcd16c2ad8e30d49bd51e110120ca802ff7c
  • Value id: 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:

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

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

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

Was this article helpful?
Sign up to give your opinion about our articles.