Skip to content

DOCS-2933-fix-salt-explanation #311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hhood-smartling wants to merge 1 commit into
base: master
Choose a base branch
from
+2 −2
Open

DOCS-2933-fix-salt-explanation #311

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions spec/job_batches_v2/job_batches_endpoints.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -608,7 +608,7 @@ x-paths:
**Job creation behavior** depends on the `mode` parameter:
- **REUSE_EXISTING**: Returns an existing job if one matches the evaluated name template. If the matching job is
cancelled, deleted or closed, creates a new job with a unique name using the specified `salt` strategy.
closed, creates a new job with a unique name using the specified `salt` strategy.
Copy link
Contributor

@vfisyuk-smartling vfisyuk-smartling Jan 19, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to the jobs facade service when mode is REUSE_EXISTING salt is applied when existing job's status is CANCELED, DELETED, or CLOSED, so the current documentation is correct.
https://github.com/Smartling/jobs-facade/blob/master/server/src/main/java/com/smartling/jobs/facade/service/JobsService.java#L113
https://github.com/Smartling/jobs-facade/blob/master/server/src/main/java/com/smartling/jobs/facade/jobs/JobApiV3Adaptor.java#L55

Copy link
Contributor

@dimitrystd dimitrystd Jan 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct, it should use salt whenever the job is in the final state.

Copy link
Contributor Author

@hhood-smartling hhood-smartling Jan 20, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi guys, I had tested this and in my sandbox salt was not applied if the job was canceled or deleted. See screenshot example in this ticket - https://smartling.atlassian.net/browse/DOCS-2933

This is also what we found when testing the Zapier app. See green box here - https://help.smartling.com/hc/en-us/articles/39746447095195-Smartling-s-Zapier-App#:~:text=If%20an%20existing%20daily%20or%20custom%20daily%20job%20is%20cancelled%2C%20deleted%20or%20closed%2C%20a%20new%20job%20is%20created%20(using%20the%20same%20job%20name%20as%20the%20previous%20daily%20job).%C2%A0If%20the%20previous%20job%20was%20closed%2C%20a%20sequence%20of%20alphanumeric%20characters%20is%20added%20as%20a%20suffix%20to%20the%20regular%20job%20name%2C%20in%20order%20to%20create%20a%20unique%20new%20job.

Is there something I'm missing?

Copy link
Contributor

@vfisyuk-smartling vfisyuk-smartling Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @hhood-smartling,
On your screenshot, I see a canceled job Daily Update 2025-12-16 (Cancelled 2025/12/16 15:01:50) and a new job Daily Update 2025-12-16. When a job is canceled, its name is changed, and a new job is created without salt because there is no job with the same name (Daily Update 2025-12-16).

Copy link
Contributor Author

@hhood-smartling hhood-smartling Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @vfisyuk-smartling

Yes, based on this behavior, we feel the current API documentation wording could be a bit misleading or confusing for users.

Specifically, this line stood out to us:

“REUSE_EXISTING: Returns an existing job if one matches the evaluated name template. If the matching job is cancelled, deleted or closed, creates a new job with a unique name using the specified salt strategy.”

From our understanding, a matching job would always be a closed job. It wouldn’t be a canceled job, since—as you mentioned—when a job is canceled, its name is updated to include a cancellation timestamp.

We also thought users might interpret “matching” to mean a job created with the same date, even if the job name technically includes a suffix and therefore doesn’t exactly match. That’s how we initially read it, which is why the wording raised questions for us.

That said, if you disagree, that’s totally fine—we’re happy to drop it. Thanks so much for taking the time to clarify this for us.

Copy link
Contributor

@vfisyuk-smartling vfisyuk-smartling Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @hhood-smartling,
My understanding is that the matching job is a job that matches the evaluated name template (based on the first sentence in the API documentation). But feel free to update it to be not confusing.
Thank you!

Copy link
Contributor

@maescomua maescomua Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given the provided use-cases - the only job state where the salt would be added is when a job is closed, other states are not applicable.
Updating the wording in documentation totally makes sense.
Thank you @hhood-smartling for testing and bringing this up!

- **CREATE_NEW**: Attempts to create a new job with the evaluated name. If a job with that name already exists,
appends a unique identifier using the specified `salt` strategy to ensure creation succeeds.
Expand Down Expand Up @@ -1107,7 +1107,7 @@ components:
**When salt is applied**:
- With **REUSE_EXISTING**: Salt is appended when an existing job with the evaluated name is in a closed or completed
- With **REUSE_EXISTING**: Salt is appended when an existing job with the evaluated name is in a closed
Copy link
Contributor

@vfisyuk-smartling vfisyuk-smartling Jan 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to the above:

Suggested change
- With **REUSE_EXISTING**: Salt is appended when an existing job with the evaluated name is in a closed
- With **REUSE_EXISTING**: Salt is appended when an existing job with the evaluated name is in a cancelled, deleted or closed

state, ensuring a new unique job is created.
- With **CREATE_NEW**: Salt is appended when a job with the evaluated name already exists, regardless of status.
Expand Down