DOCS-2933-fix-salt-explanation

[hhood-smartling]

https://smartling.atlassian.net/browse/DOCS-2933

[vfisyuk-smartling]

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

[dimitrystd]

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

[hhood-smartling]

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?

[vfisyuk-smartling]

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).

[hhood-smartling]

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.

[vfisyuk-smartling]

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!

[maescomua]

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!

[vfisyuk-smartling]

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

[maescomua]

100% agree - totally makes sense.
Thank you!