Signals Notebook: How to change the location of Entities displayed in a Page of Experiment using API

Signals Notebook (except Individual Edition) offers external API to change the location of an Entity in an Experiment. You can move the location inside a Page as well as move it to another Page in the same Experiment. This article explains how to utilize the APIs to accomplish it.

For first-time API users

If you haven't used the API document of Signals Notebook and don't know how to access to or how to use it, please refer to the knowledge base article below.

Signals Notebook: How to access API documentation?

Testing APIs

You can use PUT /entities/{eid}/layout/location for this purpose. You can test this API by following the steps in this section. Note that these steps explain how to change the location inside the Page, but you can use the same API to move the Entity to another Page by specifying the destination Page ID.

1. Open an Experiment that you can use for the test in your Signals Notebook. Make sure that the Experiment contains at least two Entities such as Text, Chemical Drawing, Table and etc. in one Page.

2. In the "Experiment Content" column on the left, click on a Page. This action will reveal the Page ID as part of the URL in the browser's address bar.

 

3. The URL should look like the one below. The text shown in bold below is the Experiment EID, and the text underlined is the URL-encoded Page ID. To get the raw Page ID, you need to replace "%3A" with ":"

https://<tenant domain>/elements/entity/experiment:f4fa58b5-4914-495c-97b2-4f77f6ebf420?focus=experiment%3A4fd06c61-5fa6-4300-b870-921cd5d272a0

4. Open API Document. Open the "Entities" section. Open "GET /entities/{eid}/layout/pages/{pageId}"

5. Click "Try it out" button in this section, then the input fields in this section becomes enabled.

6. Enter the Experiment EID in "eid" field. Enter the Page ID in "pageId" field.

 

7. Click the "Execute" button. If the API call succeeds, you should get code 200 response with a response body in JSON format.

8. Check the response and find "data"->"attributes"->"entities". This is a list of all the Entities in the Page, and the Entities are listed in the same order you see on the web page. Please note that each Entity has an "index" value that tells the location of the Entity in the Page.
 

"entities": [
    {
        "entityEid": "text:972be3ce-7bc9-43d7-92e2-8116b6a98c57",
        "entityName": "1st Text",
        "index": 0
    },
    {
        "entityEid": "grid:1d0ed60f-a51a-49c0-b088-1321a576f539",
        "entityName": "Table",
        "index": 1
    },
    {
        "entityEid": "chemicalDrawing:35a4eb8b-f386-4193-9dbf-c93c988d5e72",
        "entityName": "ChemDraw Document",
        "index": 2
    }
]

9.  Copy the values of "entityEid" and "index" for the target Entity you want to move the location.

10. Copy "digest" value that you should be able to find in the response. You need it for a parameter in the API call to update the location of the Entity.

11. On API Document under "Entities" section, open "PUT /entities/{eid}/layout/location".

12. Click "Try it out" button in this section.

13. Enter the EID of the target Entity you want to move in the "eid" field. (e.g., "chemicalDrawing:35a4eb8b-f386-4193-9dbf-c93c988d5e72").

14. Enter the digest value in the "digest" field. (e.g., "13512670").

15. In the "Example" field, replace the value of "pageId" with the decoded Page ID that you got from the URL. And replace the value of "index" with the new index you want to assign for the target Entity.

16. Click the "Execute" button. If the API call succeeds, you should get code 200 response.

17. Go back to the Experiment in Signals Notebook. Confirm the order of the Entities in the Page has been updated.