The Organization's Discover API Token in the Admin Portal
Other languages
How an organization admin sets one Discover API token every case can use for background processing, checks which cases it can open, decides whether people may reuse their own tokens, and moves cases onto the organization token.
The Organization's Discover API Token in the Admin Portal
Background processing needs a Nuix Discover API token connected to each case. Instead of every case pasting its own, an organization admin can set one organization token per Discover portal on the Settings screen. Every case of your organization on that portal then offers it, and anyone working in the case connects it with one click: Use organization token.
Nothing connects on its own: the organization token is offered in every case, and a case uses it once someone chooses it there, or once you switch cases to it from this screen.
Before you start
Discover has no separate service-account type, so the organization token is the personal API token of a Discover user you create for Claira:
- Create a dedicated Discover user, such as
claira-service. - Add it to your cases, with permission to read documents and apply coding to your destination fields.
- Sign in to Discover as that user and generate its personal API token.
Steps 1 to 3 of Setting up background processing describe each of these in Discover. Every background write-back appears in Discover as the token's account, which is why a dedicated user is recommended over a person's own token: the audit trail then shows the work as Claira's, not as a reviewer's.
Setting the organization token
The Discover API token card lists each Discover portal of your organization, with a status: Working, Rejected by Discover or Not set.
- On the portal, choose Add token.
- Paste the service user's token into Personal API token of the service user and choose Verify and save.
- Claira checks the token with Discover, and checks that it was generated on that portal. A token Discover does not accept, or one generated on a different portal, is not saved, and the card says why.
Claira never shows a saved token again. Once it is set, the portal shows Connects as and the account, Set with the date and who set it, Checked with the date it was last checked, and how many cases use it (Used in 12 cases).
When an organization token is set, Sync from Discover on the Users screen uses it to read your Discover portal.
Which cases it can open
A token connects only to cases its Discover user can open. The card says how many of your active cases on that portal the token can open, for example Can open 18 of 20 active cases.
- Show the 2 it can't open lists those cases by name. Add the service user to them in Discover (Case Setup > Users).
- Check now asks Discover again, for example after you add the user to more cases. The check reads the list from Discover at that moment and keeps nothing.
Replacing the token
When you rotate the service user's token in Discover, choose Replace token, paste the new token and choose Verify and save. Every case connected to the organization token uses the new one straight away, with nothing to do in the cases. If Discover had stopped accepting the old token, see When Discover rejects the token.
Removing the token
Choose Remove on the portal. The confirmation, Remove the organization API token?, says how many cases use it and that background processing stops in those cases until someone connects another token. Discover keeps accepting the token until you revoke it there. Choose Remove token to confirm.
Background tasks running in those cases pause at once, with their progress kept, and the person who started each one is emailed that it is paused because the API token the case used was removed or disconnected. Once someone connects another token in the case, the task can be resumed from Bulk Tasks.
While your organization's Personal API tokens option is Not allowed, no organization token can be removed: change the option first, then remove the token.
Personal API tokens
The Personal API tokens option decides whether people may connect their own tokens to cases:
| Option | What people in your organization get |
|---|---|
| People can reuse their own token across cases | The default. A token someone pastes in a case is offered back to them, with one click, in their other cases, unless they uncheck Also offer this token in my other cases. The organization token, when set, is still offered first. |
| Allowed, one case at a time | People can paste their own token, but it is used only in the case where it was pasted, and never offered in their other cases. The organization token is still offered in every case. |
| Not allowed | Every case uses the organization token, and people cannot paste their own. Cases on personal tokens keep them until you switch them. |
Not allowed can be chosen only when every portal of your organization has a working organization token. Until then it is unavailable, with the reason Add a working organization token for every portal first.
Changing this option never disconnects a case.
Personal tokens in use
Personal tokens in use lists the tokens people saved themselves, with the columns Person (who added it), Connects as (the account), Cases (how many use it), Last used and Status.
- Remove removes a person's token. The confirmation, Remove {user}'s API token?, says how many cases use it: background processing stops in those cases until someone connects another token. As when you remove the organization token, background tasks running in those cases pause at once and the person who started each one is emailed.
- The footer counts the cases that rely on personal tokens, for example 6 cases rely on personal tokens. Switch to the organization token asks Switch {count} cases to the organization token? and explains that Claira checks each case with Discover first, and that a case the organization token's account cannot open keeps its personal token. Choose Switch cases. The result says how many cases were switched ({switched} cases switched.) and how many could not be because the organization token's account cannot open them. Add that account to those cases in Discover, then switch again.
Claira never removes a personal token on its own.
On the Cases screen
On the Cases screen, a badge on each case says which token it uses: Organization token, a person's own token ({user}'s token), or No token.
When Discover rejects the token
If the organization token is revoked or expires in Discover, the portal shows Rejected by Discover.
- Your admins are emailed, once per rejection. The email goes to every member of your organization who has an email address in the Admin Portal's user directory and whose role is Organization admin or includes Manage the organization's Discover API token. The role switches on the Email screen do not apply to it.
- Background tasks pause, with their progress kept. Tasks that use the token stop where they are and show as Incomplete in Bulk Tasks; anything they already wrote to Discover stays. The person who started each one is emailed that it is paused. In each case, the Background processing section shows Needs attention, and new background scans are refused until the token is replaced.
- Field Migration does not pause. A field migration running at that moment ends as failed, with the message "Discover stopped accepting the API token this case uses. Replace it, then resume." The copies it had not made yet stay unmade.
- Replace it once. Generate a new personal API token for the same service user in Discover, then choose Replace token. Every case that uses the organization token is fixed at once.
- Then resume. People in the cases use Resume in Bulk Tasks to continue each paused task from where it stopped. Resume is refused until the case has a working token again.
Who can manage it
Admins whose role includes Manage the organization's Discover API token can set, replace and remove the organization token, change the Personal API tokens option, remove personal tokens and switch cases. The built-in Organization admin role includes it; everyone else sees the card read-only. Every change is recorded on the Activity screen under Roles and access, with the account name, never the token.
In cases, connecting a token Claira already holds needs Connect a saved API token to a case, which every User has by default. See Users and Roles.
Need help? Contact us at support@claira.to.
Was this page helpful?
Continue reading
Need more help?
Contact our support team at support@claira.to — we are here to help.