Integrate and update third-party metrics with Atlassian Goals
With Atlassian Goals, you can integrate third-party data sources to automatically update your goal metrics. This allows your team to track progress in real time, without manual data entry.
Note: This integration currently requires some technical setup using our API. We are working on a more user-friendly, UI-based solution in the future.
概要
This guide explains how to connect your external data sources to Atlassian Goals, enabling automatic updates of your goal metrics through our Metrics API.
The key concepts behind metrics and metric targets in Atlassian Goals
How to retrieve the necessary IDs for your goals and metrics
How to authenticate and interact with the API
How to update metric values programmatically - where to find further documentation and support
What does this solution offer?
Automated metric updates: Connect your own systems or third-party tools to update progress on your goals automatically - no manual entry required.
Flexible integration: Use our API to push metric values from any compatible data source.
Real-time visibility: Ensure your team always sees the latest progress toward your goals.
How does it work?
Define metrics: Set up the metrics you want to track in Atlassian Goals and attach them to your goals.
Connect your data: Use our API to securely send metric updates from your external systems.
Automate progress tracking: As your data changes, your goal progress updates automatically in Atlassian Goals.
必要なもの
Technical setup: This solution is currently API-based and requires technical setup on your side (such as writing a script or integration).
API authentication: Secure access is managed via Atlassian API tokens.
Support: Our team can provide guidance, but you’ll need technical resources to implement the integration.
主なコンセプト
Metric: is an entity that has a specific name and measurement type. For example, “number of users” would be the name of our metric, and it could have the measurement type “number.”
Metric Target: Is a metric that is attached to a specific goal and has the three numerical values:
startValue: Where the data we are using for the metric starts. For example, if we’re measuring “number of users” with our metric and we started at “2” when we first created our metric, then our
startValuewould be 2.currentValue: The data status of the metric. So if now, we have currently have 5 customers instead of the starting value of 2, then the current value will equal 5.
targetValue: The final number we would like to reach with our metric in relation to our goal. So if we want to get to 10 customers to meet a goal, then this value will be 10.
Goal: Each metric target is an instance of a metric, and each metric is attached to a goal. Updating the
currentValueof a metric target will also update the progress of a goal.
Step-by-step integration guide
Create metrics and attach them to goals
Set up the metrics you want to track in Atlassian Goals by specifying the metric name, measurement type and attaching them to your goals.
For more information, see: What is a metric? | Platform experiences | Atlassian Support
Retrieve required IDs
You’ll need two IDs:
goalId: The unique identifier for your goal.
metricTargetId: The unique identifier for the metric attached to your goal.
How to find these IDs:
goalId: Use browser Developer Tools to inspect network requests and extract the
goalId(the unique identifier for the goal).metricTargetId: Use the Atlassian GraphQL API (via the public playground or programmatically) to query for the
metricTargetIdassociated with the goal and metric.
ID formats
Here are some common IDs we use for our metrics API:
goalId: ID of the goal in the following format:ari:cloud:townsquare:<cloud-id>:goal/<goal-uuid>metricTargetId: ID of the metric target in the following format:ari:cloud:townsquare:<site-id>:metric-target/<metric-target-id>
Set up authentication
Generate an Atlassian API token and use it with your email address for Basic Authentication in all API requests.
Then, encode credentials as email:api_token in Base64 and include in the Authorization header.
Automate metric updates
Write a script or integration on your side that uses the metricTargetId to call the goals_editMetricTarget GraphQL mutation and update the metric’s currentValue.
Ensure the script handles authentication and error checking as per Atlassian’s API documentation.
Maintain integration
For each new metric or goal, repeat the ID retrieval process (or external ID mapping).
Keep API tokens secure and update them as needed.
Updating a goal metric via API
Ensure that the goal you would like to track via metric already has a metric attached to it in the Progress section before proceeding, as described here: What is a metric? | Platform experiences | Atlassian Support
In order to update the metric value, we will need to fetch the metricTargetId that is attached to a goal. In order to do this, we will first need to use the goals_ById query with the correct goalId.
| 1 | Navigate to Developer Tools on your browser and open the Network tab. Reload the page so that we can view all of the requests coming in. Once the page load has been completed, you can filter all of the incoming API requests by typing |
| 2 | You should see a request entry in the Network tab titled |
| 3 | In the payload itself, you should see under the |
| 4 | Head over to our public GraphQL playground at https://developer.atlassian.com/platform/atlassian-graphql-api/graphql/explorer/. Use the following query to get the query goals_byId {
goals_byId(goalId: "ari:cloud:townsquare:a436116f-02ce-4520-8fbb-7301462a1674:goal/20dedebf-c65e-42ba-aaeb-fc450d8d9837") {
metricTargets {
edges {
node {
id
metric {
name
}
}
}
}
}
}Replace the The response you get should look something like this: The response you get should look something like this: {
"data": {
"goals_byId": {
"metricTargets": {
"edges": [
{
"node": {
"metric": {
"name": "Ash is testing in production"
},
"id": "ari:cloud:townsquare:a436116f-02ce-4520-8fbb-7301462a1674:metric-target/86253612-b75c-4d33-af1e-5f89200c8492"
}
}
]
}
}
},
"extensions": {
"gateway": {
"request_id": "2ad79f7b-fb6e-4fbf-b071-bf0bd3d8ef5b",
"trace_id": "2ad79f7bfb6e4fbfb071bf0bd3d8ef5b",
"crossRegion": false,
"edgeCrossRegion": false
}
}
}The value you need for the next step is the
You can also do this step programmatically by sending a GraphQL request to https://developer.atlassian.com/gateway/api/graphql. Just ensure that you are attaching your Atlassian API token to the request, as per the documentation here: GraphQL API |
| 5 | Now that we have the This specific GraphQL query should be sent to 認証Our GraphQL API uses Basic Authentication for secure access. Instead of a password, you'll use your API key along with your email address. How to AuthenticateEncode your credentials in the format Header Format:
例If your email is
cURL Example:
In order to update the current value for a metric, we use the mutation goals_editMetricTarget(
$metricTargetId: ID!
$startValue: Float
$targetValue: Float
$currentValue: Float
) {
goals_editMetricTarget(
input: {
metricTargetId: $metricTargetId
startValue: $startValue
targetValue: $targetValue
currentValue: $currentValue
}
) {
success
errors {
message
extensions {
errorType
}
}
goal {
id
progress {
percentage
type
}
metricTargets {
count
edges {
node {
id
metric {
id
name
}
startValue
targetValue
snapshotValue {
value
}
}
}
}
}
}
}If you would just like to update the current value of a metric, you only need request parameters Since we already have our mutation goals_editMetricTarget {
goals_editMetricTarget(
input: {
metricTargetId: "ari:cloud:townsquare:a436116f-02ce-4520-8fbb-7301462a1674:metric-target/86253612-b75c-4d33-af1e-5f89200c8492"
currentValue: 10.2
}
) {
success
errors {
message
extensions {
errorType
}
}
goal {
id
progress {
percentage
type
}
metricTargets {
edges {
node {
id
metric {
id
name
}
startValue
targetValue
snapshotValue {
value
}
}
}
}
}
}
} |
| 6 | And now you’re all set! For automated updates, all you need to do is perform 1-4 once per integration to get the |
お困りですか?
If you need assistance with setup or troubleshooting, please Atlassian Support.
この内容はお役に立ちましたか?