← Charterly
DocumentationPrivacyEULASupport

Charterly documentation

Get started

  1. Install Charterly from the Atlassian Marketplace (Jira admin). Every site gets a 30-day free trial. After that it is $13 a month for up to 10 users, then billed per user.
  2. Open the admin page: Jira settings > Apps > Charterly project requests. It has five tabs: Templates, Requests, Audit log, Settings and Diagnostics.
  3. Open Diagnostics first. It should say Ready to create projects. If it says Charterly can't create projects, see "Diagnostics" below before going further.
  4. On Templates, click Add template, pick how projects are built, choose who may request and who approves, and click Save template.
  5. Tell your teams to open Apps > Project requests. That is where everyone requests projects, follows their requests and, if they are an approver, approves them.

Nobody needs the Administer Jira permission to request or approve. Charterly creates the project itself once a request is approved.

Templates

A template decides what a new project looks like, who may ask for one, and who approves it. The Templates tab lists every template with what it Builds, Who may request, Approval and Status (On or Off). Use Edit to change a template and Delete to remove it.

Delete asks you to confirm first. A template that still has open requests (waiting for approval, approved and queued, being created, or needing attention) can't be deleted: the confirmation lists their keys and Delete template stays disabled. Approve, reject or cancel those requests first. To stop new requests while they finish, edit the template and turn off Available to requesters. Deleting a template keeps the projects it created and its past requests.

In the template editor:

  • Template name (what requesters pick): up to 80 characters.
  • Description shown on the request form: up to 500 characters.
  • Available to requesters: turn this off to hide the template from the request form without deleting it.

How the project is built

Choose one:

  • Copy a template project (company-managed: schemes, roles, components, versions, board). Pick the Template project. Only company-managed projects are offered. Once you pick one, a box titled What new projects get from this template lists its schemes, project type, role members, components, unreleased versions, board type and whether it has a category.
  • Use a Jira built-in template (including team-managed). Pick a Jira template:
    • Team-managed Kanban (software)
    • Team-managed Scrum (software)
    • Company-managed Kanban (software)
    • Company-managed Scrum (software)
    • Business: project management
    • Business: task tracking
    • Business: process control
    • Business: document approval
    • Service: team-managed general service project
    • Service: company-managed general service project

For a copy template, the new project uses the same permission, notification, workflow, issue type, issue type screen, field configuration and issue security schemes as the template project (field configuration and issue security only when the template project has them). Then these options apply:

  • Copy project role members: on by default. Users and groups in the template project's roles are added to the same roles in the new project.
  • Copy components: on by default. Names, descriptions, component leads and default assignee settings.
  • Copy unreleased versions: off by default. Released and archived versions are never copied.
  • Create a board like the template's (Scrum or Kanban): on by default. Creates a board of the same type, with its own filter shared with the new project and handed to the project lead.
  • Same project category: on by default.

These copy options don't apply to built-in templates; Jira sets those projects up from its own template.

If you pick a team-managed project as the template project, saving is refused: team-managed projects keep their settings inside the project, so they can't be copied. Use one of the built-in team-managed templates instead.

Who may request

  • Groups (leave empty for everyone with Jira access): type to search groups.
  • Open requests allowed per person (0 = no limit): counts that person's requests for this template that are waiting, approved or being created. Up to 50.

Jira admins can request from any template that is available to requesters.

Approval

  • Create projects right away (no approval step): on means every request from this template is approved automatically and created straight away.
  • Approver groups (Jira admins can always approve)
  • Approvers (people)

The new project

  • The requester leads the project or A fixed person leads every project from this template (then pick the Project lead).
  • Make the requester a project administrator: on by default. Adds the requester to the new project's Administrators role. This works for built-in templates too.
  • Name prefix (optional): for example "Client: ". Added to the front of the project name unless the requester already typed it.
  • Key prefix (optional, up to 5): for example "CL". Added to the front of the key unless it already starts with it.

Extra questions on the request form

Click Add question to add up to 10 questions, such as "Cost center". For each one:

  • Required: the request can't be sent without an answer.
  • Add to project description: on by default. The question and answer are added to the new project's description.
  • Remove deletes the question.

Answers are always shown to approvers in the request details, whether or not they go into the description.

Requesting a project

Open Apps > Project requests and stay on New request.

  1. Template: pick what kind of project you need. You only see templates you are allowed to request. A box under it shows the template's description and whether an approver reviews each request or the project is created right away.
  2. Project name: 2 to 80 characters. If the template has a name prefix, you see Will be created as: with the full name.
  3. Project key: a key is suggested from the name. Keys are 2 to 10 characters: a letter first, then letters, digits or underscores. Click Check (or leave the field) to check it against Jira. If the key is free you see "is free". If it is taken or invalid you see Jira's reason and, when Jira has one, a Use button with a free key.
  4. What is this project for?: one or two sentences. This becomes the project description.
  5. Answer the template's extra questions. Required ones are marked (required).
  6. Click Send request (or Create project for templates that don't need approval).

Charterly also checks that no other open request already uses the same key or name, so two people can't claim the same key while waiting for approval.

After sending you see Request sent or Approved, creating your project. Click Request another project to start a new one.

If you see No project templates for you yet, your Jira admin has not shared a template with you.

Following your requests

My requests lists your requests with their key, name, template, date and status. Click Details to see everything about a request:

  • The status: Waiting for approval, Approved, queued, Creating, Created, Needs attention, Rejected or Cancelled.
  • Your description and answers, the approver's note (shown as Reason when rejected), and the History of who did what and when.
  • Setup steps once creation starts, each with a result of waiting, done, skipped or failed.
  • A link to open the project in Jira once it exists, and a link to the Tracking issue if your site uses them.

The list refreshes on its own while a project is being created. Creation usually takes under a minute.

You can click Cancel request while a request is waiting for approval or needs attention.

Approving requests

The Approvals tab shows a count of requests waiting for you, and the page opens on this tab when something is waiting.

  • Waiting for you: requests from templates you approve.
  • Recent requests you can see: decided requests from those templates.

Open Details on a request, then:

  • Approve and create: Charterly checks the key is still free and starts creating the project. If someone has taken the key since the request was made, approval is refused and you should reject the request so the requester can pick a new key.
  • Reject: needs a note in Note to the requester (required when rejecting). The requester sees it as the reason.

You can't approve your own request unless you are a Jira admin. Another approver or a Jira admin has to.

How a project is created

After approval, Charterly creates the project in the background, step by step:

  1. Create project with the template's schemes, category, lead and description (or from the Jira built-in template).
  2. Link project to request: stores the request id on the project, so a repeated attempt recognises the project it already made instead of making a second one.
  3. Project roles: copied role members, plus the requester as administrator if the template says so.
  4. Components, Versions and Board, when the template copies them.
  5. Update tracking issue, when tracking issues are on.

Steps that are already done are never repeated. If the project is created but a later step fails (for example a deactivated user or deleted group in one of the template project's roles), the project is kept, the request shows Needs attention with the failed step and Jira's reason, and an approver or Jira admin can click Retry to finish only what is left. If the key was taken by another project before creation, the request says so; cancel it and request again with a new key.

If creation stalls (for example the background job was interrupted), Charterly checks every hour and restarts any approved request with no progress for 20 minutes, up to 5 attempts.

Admin: Requests tab

  • Waiting for approval: every request waiting on an approver. Jira admins can approve or reject any request.
  • All recent requests: with Details, Cancel request and Retry.
  • Export CSV: shows the requests as CSV text (requested date, key, name, template, status, requester and decider account ids, decision date, decision note and error). Copy it into a spreadsheet or a .csv file.

Admin: Audit log

The Audit log tab records every request, decision, project creation, failed creation, template change and settings change, with when and who. Actions Charterly performs itself show Charterly as who. The tab shows every kept entry, newest first, 25 to a page; Charterly keeps the latest 1,000. Export CSV gives the same entries as CSV text.

Admin: Settings (tracking issues)

Optional. Charterly can open one Jira issue per request in a project you choose, and comment on it when the request is approved, rejected, cancelled or created. You can build filters and dashboards on these issues.

When a request is waiting for approval, Charterly also has Jira email the template's Approver groups and Approvers (people) about its tracking issue, using Jira's own notification email (sent as the requester, or as Charterly if the requester can't see the tracking project). The requester is left out. Jira admins who aren't in an approver group or named as approvers are not emailed. Requests from templates that create projects right away send no approval email. If the email can't be sent, the request still goes through and its history notes why.

Jira only sends these emails about an issue, so approver emails need tracking issues on. With tracking issues off, approvers see waiting requests on the Approvals tab.

  • Tracking project and Issue type, then Save.
  • Clear the tracking project and save to turn tracking issues off.

Tracking issues are created when a request is sent. If one can't be created, the request still goes through and its history notes why.

Admin: Diagnostics

Charterly creates projects as its own app user, so that user needs the Administer Jira global permission. Jira gives it that by default.

  • Ready to create projects: all good. The box also shows the license state.
  • Charterly can't create projects: in Jira settings > System > Global permissions, make sure the atlassian-addons-admin group has Administer Jira, then click Check again.

Licensing and trials

Charterly is paid through Atlassian, with a 30-day free trial. Pricing is $13 a month for 1 to 10 users, then $2.30 per user per month for users 11 to 100, with lower per-user rates for larger sites (see the pricing tab on the Marketplace listing). There is no free tier.

If the license is not active, a License not active banner appears on both pages and:

  • Send request is disabled, and sending a request is refused.
  • Approve and create and Retry are refused with a message to renew in Apps > Manage apps.
  • Rejecting and cancelling requests still work, and admins can still edit templates and settings.
  • Existing requests, their details and the audit log stay readable.

Permissions and data

  • Charterly runs on Atlassian's Forge platform and sends nothing to any outside server. The app has no external network permissions.
  • Who can do what is checked on every action, from your signed-in Jira account: your groups and whether you hold Administer Jira. Only Jira admins can see the admin page, change templates or settings, read the audit log or export CSV.
  • Requesters see their own requests. Approvers see requests for the templates they approve. Jira admins see everything.
  • Charterly stores templates, settings, requests (name, key, description, answers, status, setup step results, decision notes, history) and the audit log in Forge storage for your site, with Atlassian account ids for requesters, approvers and admins. It does not store email addresses.
  • Requests are deleted automatically 1 year after their last update. The audit log keeps the latest 1,000 entries. Templates are kept until you delete them.
  • Group memberships and permissions are checked live and not stored. The template project's configuration is read when a project is created and not stored.
  • Each created project gets a project property named charterly-request that links it to its request.

Limits and known gaps

  • Team-managed projects can't be used as a copy source; use a built-in team-managed template instead.
  • Copy templates carry over schemes, role members, components, unreleased versions, a board and the category. Issues, filters other than the new board's, automation rules, project shortcuts and released or archived versions are not copied.
  • New projects share the template project's schemes rather than getting copies of them. Changing a shared scheme changes every project that uses it.
  • Boards are only created on sites with Jira Software and when the template project has a Scrum or Kanban board. Built-in service templates need Jira Service Management on the site.
  • Extra questions are free-text fields. Answers go into the project description or stay in the request; they are not mapped to custom fields or project properties.
  • Approvers are emailed about new requests only when tracking issues are on, because Jira's notification email is always about an issue. Otherwise they see the count on Approvals. Charterly never sends email outside Jira.
  • The request page lists your latest 50 requests, and approvers see up to 100 recent requests. Export CSV on the Requests tab includes all kept requests (up to the latest 2,000).
  • A template can't be deleted while it has open requests. Deleting it later keeps its past requests and created projects.
  • Up to 10 extra questions per template; project names up to 80 characters; key prefixes up to 5 characters.

FAQ

Does it work with team-managed projects? Yes. Use a built-in template: team-managed Kanban, team-managed Scrum or the team-managed general service project. The requester can still be made project administrator.

Are the template project's roles applied to the new project? Yes. With Copy project role members on, every user and group in the template project's roles is added to the same roles in the new project. The setup steps show how many grants were made, and anything Jira refused is listed by role.

What if I change the template project after projects were created? Charterly reads the template project each time it creates a project. Switch the template project to a different scheme, or change its roles, components or board, and the next project created from it follows. Projects already created are not changed by those edits.

Can different teams have different templates and approvers? Yes. Each template has its own requester groups, approver groups and named approvers, and approval can be switched off per template.

How will approvers know a request is waiting? The Approvals tab shows a count and opens first when something is waiting. Turn on tracking issues in Settings and Jira also emails each template's approver groups and named approvers when a request arrives.

What happens if creating a project fails halfway? The project is kept, the failed step and Jira's reason are shown in Setup steps, and Retry finishes only the remaining steps. A project is never created twice for the same request.

Do people need Jira admin rights? No. Requesters and approvers only need to be in the groups you choose. Charterly's app user creates the project.

Can someone approve their own request? Not unless they are a Jira admin.

Uninstalling and your data

Projects created by Charterly are normal Jira projects and stay after you uninstall, as do tracking issues and their comments. When the app is uninstalled, Atlassian deletes Charterly's stored templates, requests, settings and audit log for your site.

Support

Open a request in the Great Work support portal (linked from the Marketplace listing and from Contact Great Work support on the Project requests page) or email hello@greatwork.company. First response within 1 business day.