Authorization Link

Function: a!authorizationLink()

Defines a link to authorize a user for a connected system that uses the OAuth 2.0 Authorization Code grant. Links can be used in charts, grids, hierarchy browsers, images, link fields, milestones, pickers, and rich text.

Parameters

Name Keyword Type Description
Label label Text Text displayed as the link name the user clicks on.
ConnectedSystem connectedSystem Connected System Connected system used to generate the authorization link. Provide the connected system value returned by an integration when the response indicates that the user needs to authorize.
Visibility showWhen Boolean Determines whether the component is displayed on the interface. When set to false, the component is hidden and is not evaluated. Default: true.

Notes

  • Be sure to read through the external system's documentation to understand what is returned when the user needs to authorize or reauthorize
  • For integrations getting data, use dot notation. For integrations writing data use fv!connectedSystem.
  • A link created by a!authorizationLink() opens in a new browser window.
  • For mobile, a link created by a!authorizationLink() will open the device's default browser
    • Authorization links are made for mobile, so you don't need to worry about the user not being signed-in in the mobile browser.
  • If the mobile user is signed in as one user in the mobile browser and a different user in the mobile app, authorization will fail.

Examples

When connecting with OAuth, integrations can either get data from or post data to another system

Integrations Retrieving Data

Assuming that the integration used a custom error message that returned Access_token when an access token was missing, the following interface expression will provide an authorization link.

1
2
3
4
5
6
7
8
9
10
11
12
load(
  local!integrationResult: rule!EXAMPLE_OAuthIntegration(),
  a!linkField(
    label: "Example Authorization Link",
    /* show when */
    showWhen: local!integrationResult.error.message = "Access_token",
    links: a!authorizationLink(
      label: "Authorize",
      connectedSystem: local!integrationResult.connectedSystem
    )
  )
)
Integrations Writing Data

If the integration is writing data to another system via OAuth, the integration would be called as a result of a save. These types of integrations, by default, return onSuccess and onError. fv!connectedSystem is returned when there's an error and can be retrieved through the onError parameter and used to populate the authorization link field.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
load(
  local!results,
  local!connectedSystem,
  local!verify,
  a!sectionLayout(
    contents: a!columnsLayout(
      columns: {
        a!columnLayout(
          contents: {
            a!buttonLayout(
              secondaryButtons: {
                a!buttonWidget(
                  label: "Save Changes",
                  saveInto: {
                    a!save( local!verify, true),
                    rule!EXAMPLE_OAuthIntegration(
                      onSuccess: a!save( local!results, fv!result),
                      onError: a!save( local!connectedSystem, fv!connectedSystem)
                    )
                  }
                )
              }
            ),
            a!linkField(
              label: "Authorization After Write Attempt",
              showWhen: and(not(isnull(local!connectedSystem)), not(isnull(local!verify))),
              links: a!authorizationLink(
                label: "Authorize",
                connectedSystem: local!connectedSystem
              )
            )
          }
        )
      }
    )
  )
)

See Also

OAuth 2.0: Authorization Code Grant, Link, Paging Grid, Images

FEEDBACK