Status Reports

Status reports in smenso are structured project-level summaries used to communicate progress, risks, achievements, and key metrics at defined intervals (e.g. weekly, monthly, milestone-based).

Lifecycle: Draft → Published

Each status report moves through two states:

Typical API workflow:

1. Create a status report → starts as a draft
2. Update the draft (add content, set fields, attach files)
3. Publish by setting isPublished: true → becomes immutable

To correct a published report, create a new one.

Available Endpoints

Integration JSON API

JSON API operations are asynchronous: the response returns a ticketId. Poll GET /api/integration/status/json/{ticketId} to retrieve results.

Integration XML API

XML API operations are synchronous: the response directly returns the StatusReportId (or error details).

Related Endpoints

Key Fields (JSON API)

The following fields are available on the statusReport object. See the endpoint reference for the full schema.

⚠️

Note: The exact integer values for overallStatusId, timeStatusId, costStatusId, and goalStatusId are not yet documented in the API reference. Contact smenso support or check your workspace configuration for the mapping.

Status Date vs. Publication Date

Example: Create a Status Report (JSON)

POST /api/integration/statusreport/json
Content-Type: application/json
Authorization: Bearer {token}

{
  "projectId": "a1b2c3d4-...",
  "statusReport": [
    {
      "title": "Monthly Status – June 2025",
      "statusDate": "2025-06-30T00:00:00",
      "overallStatusId": 1,
      "progressManual": 72,
      "explanation": "<p>Sprint 4 completed on time. Two features deferred to next sprint.</p>",
      "nextSteps": "<p>Begin Sprint 5. Review deferred items with product owner.</p>",
      "isPublished": false
    }
  ]
}

Response:

{
  "ticketId": "e5f6g7h8-..."
}

Poll for results:

GET /api/integration/status/json/{ticketId}

Example: Publish a Status Report (JSON)

PUT /api/integration/statusreport/json
Content-Type: application/json
Authorization: Bearer {token}

{
  "projectId": "a1b2c3d4-...",
  "statusReport": [
    {
      "id": "the-report-id-...",
      "isPublished": true
    }
  ]
}

Example: Create a Status Report (XML)

<create>
  <Base>
    <ProjectId>a6a74aea-1f45-4b10-8477-9476ca3f6903</ProjectId>
    <Title>Monthly Status – June 2025</Title>
    <ProgressManual>72</ProgressManual>
  </Base>
</create>

Successful response:

<Result>
  <HasErrors>false</HasErrors>
  <StatusReportId>2919899c-69a9-4ccb-9844-7b3e790570ad</StatusReportId>
</Result>

⚠️

Only one draft per project can exist at a time. If a draft is already pending, the API returns an error: "Can't add a new status report, because a draft is pending for project {id}."

Progress: Computed vs. Manual

Status reports have two separate progress fields:

When reading a report via API, progressComputed reflects the system's suggestion at the time the report was saved or published. When writing, set progressManual to provide an explicit value.

RichText Content

The explanation and nextSteps fields support standard HTML:

{
  "explanation": "<p>Sprint 4 completed. <strong>Key achievement:</strong> Payment module released.</p><ul><li>3 bugs fixed</li><li>Performance improved by 15%</li></ul>"
}

Flavor references in RichText

In the smenso UI, users can embed dynamic flavor values (e.g. from project master data) directly into explanation and nextSteps. These references update automatically while the report is a draft and are frozen at the time of publishing.

When reading published reports via API, the explanation and nextSteps fields will contain the resolved, static HTML values - not the original flavor references. When writing via API, plain HTML is expected; dynamic flavor references are a UI-only feature.

Templates

Status reports can be created from templates for consistent structure across projects.

JSON API:

POST /api/integration/template/statusreport/create/json/{templateId}

XML API:

POST /api/integration/template/statusreport/create/{templateId}

When creating from a template, explanation and nextSteps are pre-filled from the template. For the XML API, ProjectId, Title, and ProgressManual are required even when using a template. Other fields (status IDs, progress, dates) must be set individually.

Attachments & Comments

• Attachments can only be uploaded after the report has been saved as a draft - not during the initial create request. See Attachments Guide.
• Comments can be added or retrieved via dedicated endpoints. See the Comments endpoints.

Permissions

Status reports respect project-level permissions. If a user cannot perform an action in the UI, the API will reject it as well. Published reports can be deleted but not edited, regardless of the API used.

Further Reading

• Status Reports – smenso Help Center – Workflows and UI documentation
• Integration Tickets – How async processing works (JSON API)
• Flavors Guide – Custom fields in reports
• Attachments Guide – Upload and manage files
• Templates Guide – Creating resources from templates

FAQ

Do I need to poll after creating or updating a report?

Only for the JSON API. It processes requests asynchronously and returns a ticketId. The XML API responds synchronously and returns the StatusReportId directly.

Which fields are required?

For the JSON API: projectId and title. For the XML API template endpoint: ProjectId, Title, and ProgressManual.

How do I publish a report?

Send a PUT (JSON) or POST (XML) with isPublished: true. Once published, the report is locked and can only be deleted, not edited.

Can I have multiple drafts per project?

No. Only one draft can exist per project at a time. Attempting to create a second draft returns an error.

What is the difference between statusDate and publicationDate?

statusDate is the period the report covers and can be set freely. publicationDate is set automatically on publish and is read-only.

What are the correct field names - description or explanation?

The correct field name in the JSON API is explanation, not description. The same applies to status fields: use overallStatusId, timeStatusId, costStatusId, and goalStatusId (integer IDs), not enum strings like Green or Yellow.

What integer values do the status ID fields accept?

overallStatusId accepts values 1-7; timeStatusId, costStatusId, and goalStatusId accept 0-4. The mapping of these integers to labels (e.g. Green/Yellow/Red) is not yet documented - check your workspace configuration or contact smenso support.

When can I attach files to a report?

Only after the report has been saved as a draft. Attachments cannot be uploaded in the same request as the initial create.

What is the difference between progressComputed and progressManual?

progressManual is explicitly set by the user or via API. progressComputed is calculated automatically by smenso based on open and completed tasks in the project. The calculation can be filtered in the project's status settings to only include tasks matching specific criteria. When writing, use progressManual; progressComputed is effectively read-only.

Can I write flavor references into explanation or nextSteps?

No. Dynamic flavor references are a UI-only feature. Via API, both fields accept plain HTML only. When reading a published report, the fields contain the resolved static HTML - flavor values are already baked in at the time of publishing.

Do API permissions mirror the UI?

Yes. If a user cannot perform an action in the UI, the API will reject it as well.