Just wanted to share some quick things I’ve learned about migrating to use the newq Chronicle API endpoints:
1. The APIs are maturing (but not uniformly)
Over roughly the last four months, a number of endpoints that were previously available only through the unstable v1alpha API have become available through production-ready v1 endpoints.
There are still exceptions, though.
A number of endpoints with “legacy” in their names remain available only through v1alpha, largely because their payloads still mirror the structure of the older SOAR APIs.
2. Your GCOM migration state matters
Some functionality will not work completely until the tenant has completed GCOM Stage 2 migration.
This has been particularly noticeable with integrations.
For example, exporting an integration from a migrated tenant and importing the resulting ZIP into a tenant that has not yet migrated currently isn't viable for us.
That can leave manual transfer of custom actions as the only practical option.
3. Migrating custom actions is only part of the job
A lot of our effort has gone into rewriting custom actions to use Chronicle APIs, but legacy API dependencies can hide in many other places.
Don't forget to:
- Update marketplace integrations to versions that have themselves migrated to Chronicle APIs.
- Migrate managers, jobs and connectors, not just actions.
- Update playbooks to use the migrated custom actions.
- Update every connector instance and job instance to use the migrated versions.
- Repoint Quick Actions to the new actions.
- Reconfigure relevant integration instances, particularly Google Chronicle, with credentials intended for the Chronicle APIs.
Previously saved legacy service accounts and newer service accounts can coexist in ways that result in continued use of the legacy APIs if you're not careful.
It's very easy to think you've migrated the content while some of the surrounding configuration is still keeping the old dependency alive.
4. External scripts require an authentication migration too
Local scripts interacting with the old APIs don't simply need new endpoints.
Their authentication model also needs to change.
For us, that means moving away from SOAR API keys and toward mechanisms such as Application Default Credentials.
So the migration inventory isn't just:
Which scripts call the old API?
It should also include:
How does each of those scripts authenticate?
A design lesson I learned along the way
Early in the project, we made a design decision to move custom functionality into the Google Chronicle integration.
The reasoning was sensible: we could reuse the integration's existing authentication and marketplace managers rather than solving Chronicle API authentication ourselves anew.
I'm finishing the migration using that architecture.
But I learned something recently that would have influenced the original design.
For many of our use cases, the Siemplify.Session object could also have abstracted away that authentication requirement.
