How to access, preview or create a document from a third-party application by using an URL?

To facilitate integration, Athento offers the ability to use URLs (which can be linked or embedded in e-frames) to preview, create or consult documents.

With these URLs, it is possible to access a document by entering metadata values so that Athento can locate it and present it to the user.

Preview the main file

For this, the following pattern will be used in the URL:

https://app.athento.com/file/view/_/?filter=<filtro>

where,

• <filter>, is the set of fields (with their values) that Athento will use to locate the document containing those values in the indicated fields. 
  NOTE: the filter value must be encrypted according to Athento's policy.

It is important to note that, since there is a possibility that several documents match in the indicated filter, the fields used must be configured as key fields. If it happens that several documents match in the filter, Athento will show the first document located from the filter result.

NOTE: Key fields are those whose values will be unique in each Athento document.

Creating documents

In addition to being able to filter only to display a document by its fields, this functionality offers different URL parameters that allow creating a new document if it is not found, and/or to display it in Carrousel and List mode.

In the case of creating the document if it is not located with the fields indicated in the filter, the create_if parameter will be used:

https://app.athento.com/file/view/_/?filter=<filtro>&create_if=true

where, after filtering, if Athento does not find the document, it will create it and access it with the fields. The document will be created in the user's default space and on the default form type of that space.

If we want to indicate on which space and using which type of form to use for the creation in case the filter does not locate any document, we would have:

https://app.athento.com/file/view/_/?filter=<filtro>&create_if=true&serie=<serie>&type=<tipo>

where,

• <series>, is the name (or uuid) of the destination space where the document is to be saved in case it is not found by the filter.
• <type>, is the name of the form type that will be used to create the new document in case it is not found by the filter.

Previewing related documents

In addition to the visualization and/or creation of the document using the field filter, Athento can preview the related documents. This is very useful for integration cases where the client needs to preview the related document(s) by embedding this URL.

To preview a document using the filter, we will use the display parameter, like this:

https://app.athento.com/file/view/_/?filter=<filtro>&display=<modo>

where,

• <mode>, is the display mode we want to show. There are two types of previews: "carrousel" or "list".
  The carrousel mode will show a carrousel with the previews of the related documents.

• • The list mode will display a list of related documents and operations on the documents themselves.

NOTE: It is important to highlight that the preview can be used in the URL in addition to all the previous functionalities, that is to say, besides filtering by metadata to locate the document we could create it if it does not exist, using the space, the type of form to finally preview it in the way we want.

Security

To perform the embedded preview, it is necessary to use an additional security token in the URL that will control access to Athento, leaving the URL in this way:

https://app.athento.com/file/view/_/?token=<token>&filter=<filtro>&display=<modo>

where,

• <token>, is the limited-use access token.

To obtain a security token for the use of previewing a document by filtering it is necessary to obtain it with the following authenticated API call (any type of authentication available in Athento can be used to make the call, for example BasicAuth).

GET https://app.athento.com/users/api/access/access_token/?duration=<duracion>

where,

• <duration>, is the duration the token will have before it expires and cannot be used. The duration format is based on time units, for example, use "1d5h" to set a duration of 1 day and 5 hours. Possible units are "s" for seconds, "m" for minutes, "h" for hours, "d" for days. Some examples:
  5m: duration of 5 minutes
  10h: duration of 10 hours
  20d: duration of 20 days
  15d10m30s: duration of 15 days 10 minutes and 30 seconds.