HaloPSA Integration

ScopeStack integrates with HaloPSA to push approved project details into HaloPSA and create a project with milestones and tasks from the elements of your ScopeStack project.

Prerequisites

• A HaloPSA Application registration with the permissions below
• A HaloPSA agent for that Application to authenticate as, with the permissions below
• ScopeStack Connected Apps permission at the Manage level

Setting Up in HaloPSA

1. Navigate to Configuration > Integrations.

2. Click HaloPSA API. The Integrations page lists available integration categories; select HaloPSA API to continue.

3. Click View Applications. The HaloPSA API page shows general API settings and a View Applications button that opens your registered application list.

4. Click New in the top-right corner of the Applications page.

5. On the Add Application page, enter an Application Name (something with “ScopeStack” in it is recommended) and set the authentication method to Client ID and Secret (Services). Set Login Type to Agent, then use Agent to log in as to choose the HaloPSA agent this Application will authenticate as. Click Save. The page will display your Client ID and Client Secret after saving.

   Note: Write down and keep your Client Secret immediately — it is only shown once.

   The agent you choose here matters. See HaloPSA Agent Permissions below.

6. On the Applications page, click the Permissions tab. Click the edit button at the top of the page, check the all permission checkbox, and save. ScopeStack requests the all scope when it authenticates, so grant all rather than a narrower scope such as all:standard.

7. Click the Security tab. Enter https://app.scopestack.io in the CORS Whitelist field and click save.

HaloPSA Agent Permissions

HaloPSA applies two layers of access control to an API Application, and both have to allow an action for it to succeed. The Permissions tab in step 6 sets what the Application may do. The agent you picked under Agent to log in as sets what that agent may do. HaloPSA’s documentation states that an Application’s permissions “will apply in addition to the agent/role restrictions,” so checking all on the Application does not lift a restriction that exists on the agent.

Use a dedicated agent for this rather than a person’s login, so the integration’s access does not change when someone’s role does.

This is what the integration does in HaloPSA, and the access each part needs:

In an agent’s role configuration, two of those map to fields HaloPSA documents directly: Tickets Access Level: Read and Modify and Can add new Tickets: Yes. The agent also needs read access to customers and no ticket-type restriction, which integrator documentation gives as Customers Access Level: Read Only and Allow use of all Ticket Types: Yes. We have not confirmed those last two labels against HaloPSA’s own documentation, and field labels vary between HaloPSA versions. HaloPSA’s guide to restricting an agent’s access  covers where these settings live.

Three restrictions are worth checking specifically, because each produces incomplete results rather than an error:

• Ticket type access. In HaloPSA a project is a ticket type, and so is a project task. If the agent’s role limits which ticket types it can use, both have to be included, with create and edit rights.
• Team and client scope. The agent has to be able to see the teams and clients your projects belong to. An agent scoped to a subset produces a short Company dropdown in ScopeStack, or a project that looks like it has fewer tasks than it does. The same applies to the opportunity sync: an agent that cannot read opportunities returns none, and the connection still reports as connected.
• Delete rights. If you remove a service from a ScopeStack project and push again, ScopeStack deletes the matching HaloPSA ticket. An agent without delete rights leaves that ticket behind in HaloPSA, and ScopeStack does not report it.

An agent with administrator-level access satisfies all of this and is the quickest way to get connected. If your security policy calls for a scoped agent, build it to the table above.

Configuring in ScopeStack

Have your HaloPSA Host, Client ID, and Client Secret ready. Navigate to Settings > Connected Apps and click the HaloPSA tile.

On this screen: The Connected Apps page lists available integrations as tiles. Locate the HaloPSA tile and click it to open the integration setup page.

On this screen: The HaloPSA setup form prompts you for your HaloPSA Host URL, Client ID, and Client Secret. Fill in the values from your HaloPSA application registration.

Configuration Options

HaloPSA Host

Your company’s HaloPSA URL (e.g., companyxyz.halopsa.com). This is usually the first part of the URL you see while setting up the integration on HaloPSA’s website.

Client ID

Found on the HaloPSA Application Details page.

Client Secret

Found on the HaloPSA Application Details page. This is only shown once at creation time.

Verifying the Connection

After entering your credentials and clicking Submit, your integration with HaloPSA is complete. The Connected Apps page will show a connected status for the HaloPSA tile.

Creating a HaloPSA Project from ScopeStack

ScopeStack maps project elements to HaloPSA as follows:

• ScopeStack Project Name > HaloPSA Project Name
• ScopeStack Phase > HaloPSA Milestone
• ScopeStack Services > HaloPSA Project Task
• ScopeStack Sub-Services (if selected) > HaloPSA Project Subtask or Project Task, depending on the task-creation option you choose (see below)
• ScopeStack Governance Items (if selected and assigned to a phase) > HaloPSA Task named “Project_Management”

Requirements

• The project must be approved in ScopeStack
• HaloPSA Connected App must be configured

Step-by-Step

Once your project is approved in ScopeStack, you will have the option to Create PSA Project from the project’s Overview tab.

Note: Whether the API triggers a push depends on the API version you call.

• v1 — creating a psa_project persists the record but does not trigger the push. Nothing is created in your PSA. Push with the Create PSA Project button on an approved project.
• v2 — POST or PATCH to /v2/projects/:id/psa-project does trigger the push automatically, in the background. Do not also click the in-app button while that push is still running: until it finishes ScopeStack has no PSA project ID yet, and a second run creates a second project in your PSA.

The platform will take you to a configuration screen where you need to define:

• Estimated Start and End Date for your project.

• HaloPSA Company — options are populated from your HaloPSA instance.

• Status — options are populated from your HaloPSA instance.

• Priority — options are populated from your HaloPSA instance.

• How Tasks should be created in HaloPSA — a dropdown that controls how Services and Subservices map to HaloPSA. The four options are:

  • Create a Project Task for each ScopeStack Service — one Project Task per service; subservices are not pushed.
  • Create a Project Task for each ScopeStack Service and create a Project Subtask for each ScopeStack subservice — a task per service, with each subservice nested underneath it as a subtask.
  • Create a Project Task for each ScopeStack Service and Subservice with revenue greater than 0 — per service, one or the other, never both: if the service itself carries revenue it becomes a Project Task and its subservices are not pushed; if it does not, but one of its subservices does, tasks are created for that service’s subservices instead.
  • Create a Project Task for each ScopeStack Subservice — one task per subservice.

  Only …create a Project Subtask for each ScopeStack subservice nests subservices beneath their service’s task. In the …with revenue greater than 0 and …for each ScopeStack Subservice options, subservice tasks attach directly to the project, so the parent-service relationship is not represented in HaloPSA.

• Create PSA tasks for ScopeStack Governance Items? — if checked, creates HaloPSA Tasks from your individual governance items in ScopeStack.

After you complete your configuration and press Submit, it may take a few minutes for the project to be created.

Updating a Project

After creating the HaloPSA project, resubmitting from the PSA Integration section will add any new services to the PSA project, but will not update existing services.