Overview of External mode for ElementsGPT
We have developed a new "External" mode for ElementsGPT story generation enabling you to use your own proprietary LLM systems to complete the story generation without depending on Elements' use of AI providers. This allows you to feel secure in the use of your data with AI.
This "External" mode is an asynchronous action triggered when you auto-generate stories from a process map in Elements. Instead of generating the stories in Elements, using our LLM provider and connection, we instead create a payload of the story and prompt information that gets sent to an endpoint specified by you. This allows you to generate the stories using your own LLM applications and send the results back to Elements. We create placeholder stories and those IDs are contained in the payload so you can update the correct story, keeping the link between the story and the diagram activity intact.
Prerequisites
Corporate Management set up for your domain
External mode for GPT turned on for your Corporate Management
Endpoint specified with Client ID and secret (see below)
External Mode for GPT in Corporate Management
When External mode is active on Corporate Management it is active by default on all spaces within that Corporate domain. If you turn external mode off, it then is turned off for all contained spaces too. There is currently no option to select specific spaces within the domain to have External mode activated.
How does it work?
When External mode is active, Elements will connect to your specified LLM application and does not use our own AI / LLM connections.
The following features are inactive when External mode is used, as we are not able to support external applications in place of them:
Architecture
User goes to a UPN process and selects the activities they want to generate stories from. They confirm the action to auto-generate stories using AI. The request is sent to the Elements story generation module.
A new placeholder story is generated and linked to the activity. If there are multiple human or system resources there may be more than one story per activity as per these rules.
A payload is sent, containing the temporary story ID, and the prompt data, is sent to the endpoint specified (the generative AI application you have added in Elements).
Code is sent back to Elements to confirm if the request was successful.
Your AI application generates the user story using the data in the payload sent by Elements.
^
^
Optional: update Jira with the story information from your application.
^
The stories in Elements are updated using our stories API.
Code is sent back to confirm if the request was successful.
Expected data structure
When Elements sends the request you will receive the data in the following structure, as a JSON.
{ action: string, // 'storyGeneration'
prompt: [ { role: string, // 'system' | 'user' content: string } ], // Array of prompt messages
actionData: { storyId: string },
recommendedConfig: {
OpenAI: { model: string[], // ['gpt-4-1106-preview', 'gpt-3.5-turbo-1106']
max_tokens: number, // 4096
temperature: number, // 0
top_p: number, // 1
response_format: {
type: string // 'json_object' } } } }
OAuth authentication
We use OAuth to authenticate the connection to your application. When requesting the token we expect the response in the following format.
{ access_token: String,
expires_in: Number // time to live (TTL), in seconds }
Sending stories back to Elements
To send stories back to Elements you can use the stories API to update the placeholder stories with your generated ones. We provide the story ID in the original payload so you can easily find the correct story to update.
Visit developer.elements.cloud for in depth documentation on how to use this API.
Configuring External Mode
Setting up endpoints
To use External mode you must specify 2 key endpoints: one for the OAuth token to be retrieved, and one for the data to be sent to (i.e the application).
To see and change the External mode settings you must be a Corporate Admin in the space.
Navigate to Corporate Settings, open the "Config" tab (6th icon down on the left) and navigate to "External Settings"(third tab along the top).
You will need to provide the following information to set up the connection to your External GPT application:
1: External GPT OAuth URL
This is the URL for OAuth authentication so Elements can request a bearer token to access the application.
2: External GPT URL
The URL endpoint of the External LLM application you have created.
3. External GPT Client Id
The Client Id for your application.
4. External GPT Secret
The Client Secret for your application.
Once provided, press "Submit" to save the details. You can change or delete the details at any time. If you delete the details and do not provide new ones, the User Story generation feature will not work until new valid information is submitted.
Generating stories
Now that you're set up with the client settings you can start generating stories.
We recommend reading the instructions in this article to understand how story generation works and the prerequisites to do this in Elements.
Navigate to the map you want to generate stories from, select the boxes, right-click and select Generate stories (AI).
This will then generate and trigger the payload to send to your specified endpoint, and generate the placeholder stories for you on the diagram. They should look something like this:
Each story can then be updated, using the Elements Stories API and the unique ID for each story.
Configuring Permissions
When ExternalGPT is active, the default is for all new spaces within your domain to use your external LLM application.
However, there are 2 ways that you can disable specific spaces from using it so that the full ElementsGPT capability is available. This can allow you or other users to still benefit from and explore all the other AI capabilities in Elements.
Disable for a single space
To disable ExternalGPT on a specific space you must have Corporate Admin permissions. Then complete the following steps:
Open Corporate Settings
Open the "Spaces" tab from the list on the left hand side
Navigate to the Space you want to turn ExternalGPT off for
Select the Space, and in the right hand panel, open the 3rd tab down with the fingerprint icon ("Access" tab).
Toggle on "Disable External GPT for space"
This space now has access to all the standard ElementsGPT functionality, and does not use your external application for LLM calls.
This action can be reversed.
Disable for all spaces
If you decide that you want to disable or enable the feature for all spaces under your Corporate domain, you can go to "Policies". Turn the toggle on for "Disable External GPT for all spaces". Once this is done all spaces will no longer use External GPT. If you turn it back on, all spaces will use External GPT. Note that it will not remember the previous settings if you had some spaces with the feature overridden/disabled.
For further assistance you can contact us using the blue chat box in the bottom right hand corner of the screen, or email us at success@elements.cloud.