Layer7 API Management

Hi There,

I have a folder in dev called CustAPIFolder which contain a API service called custcreate which is in prod,now as part of the requirement i am building two more api's i wanted to promote only this two api's to higher env keeping untouched(custcreate API) ,which is already promoted to prob.How could i do this from GMU? Pls advice.

Hi Popleys,

So from what I understand, you have this scenario:

PROD
--CustAPIFolder
   --custCreate

DEV
--CustAPIFolder
   --newAPI1
   --newAPI2

And you want to move the new APIs to PROD so eventually you get this:

PROD
--CustAPIFolder
   --custCreate
   --newAPI1
   --newAPI2

This can be done using three GMU commands, which I'll explain in detail. I'm assuming you have Gateway v9.3, and GMU v1.5 or later. If not we can revisit the steps to take for other versions. I would also take a snapshot of the Gateway if you are on a Virtual Appliance so we can roll back any changes incase something goes amiss. I apologize if you already know some of this information but I figure it's best to provide as much knowledge as possible incase you have immediate questions.

1. $./GatewayMigrationUtility.sh migrateOut--argFile dev.properties --folderName CustAPIFolder --dest apiBundle.xml
- --argFile is a file in which you would describe your hosts, username, passwords, and other arguments
- --folderName means we will export the folder name 'CustAPIFolder' and all it's contents
- --dest is the result of the file export 

2. ./GatewayMigrationUtility.sh manageMappings --srcPath /CustAPIFolder --targetPath /CustAPIFolder --type folder --bundle apiBundle.xml

- Here we are modifying our CustAPIFolder folder from our Dev (given by srcPath) to map to the CustAPIFolder folder from Prod (given by targetPath). If your folder names are different in Dev and Prod, this is where you would customize the folder names. Also if for example your CustAPIFolder is nested in other folders, just specify the correct path for your folder (ie, if CustAPIFolder is under a test folder, this is your path: /test/CustAPIFolder).
- --type is the type of entity you are modifying and --bundle is the name of the bundle file to modify.

3. ./GatewayMigrationUtility.sh migrateIn --bundle apiBundle.xml --argFile prod.properties --results apiBundleResults.xml --test

- Here we are applying the migrateIn in test mode. Similar to migrateOut, prod.properties contains host, username, password, and other information needed for migration. In the results file generated, we should see that the APIs have a "CreatedNew" action taken, and the folder which we changed to map by path should have "UsedExisting" action taken.
- When this is satisfactory, rerun the command without the --test option

Let me know if this worked for you and if you have any other questions.

Thank you very much in providing in detail.But there is slight misunderstanding the below is how i have now

I am interested in moving the 2 new files, if i go with the whole folder migrate then it may overwrite with the custcreate service which don't want to happen.

Hi,
That's no problem, the same steps will still work. We need to add an extra step.

1. $./GatewayMigrationUtility.sh migrateOut--argFile dev.properties --folderName CustAPIFolder --dest apiBundle.xml

2. ./GatewayMigrationUtility.sh manageMappings --srcPath /CustAPIFolder --targetPath /CustAPIFolder --type folder --bundle apiBundle.xml

- Modifies the folder from dev to point to prod

3. ./GatewayMigrationUtility.sh manageMappings --srcPath /CustAPIFolder/custCreate --targetPath /CustAPIFolder/custCreate --type service --action Existing --bundle apiBundle.xml

- Modifies the custCreate service from dev to point to prod, and to use the existing service (ie: Do not update)
- If you do want to update the service on prod, change the --action to Update

4. ./GatewayMigrationUtility.sh migrateIn --bundle apiBundle.xml --argFile prod.properties --results apiBundleResults.xml --test

- in the apiBundleResults.xml, we expect to see the newAPI1 and newAPI1 have 'CreatedNew' as action taken, and custCreate has 'UsedExisting' as action taken
- When this is satisfactory, rerun the command without --test

Let me know if this works for you.

if only one or two service, you can use "--serviceName <name>" flag for migrateOut to only migrateOut one service.

Thanks for the detailed explanation.Please could you provide a sample manageMappings file which may contain the following.

• (name)  must be unique
• Target entity not found

In fact i want to use an existing group and identity provider for the new policy(API).Am getting the following error.Not sure what should i update to prevent the below error coming while migratein to higher environments

<l7:Mapping action="NewOrUpdate" errorType="UniqueKeyConflict" srcId="1be05876aa22069adc828b594052758a" srcUri="https://ESFIDTAPIMGMT31.rci.rogers.ca:9443/restman/1.0/identityProviders/1be05876aa22069adc828b594052758a" type="ID_PROVIDER_CONFIG">
<l7:Properties>
<l7:Property key="ErrorMessage">
<l7:StringValue>(name) must be unique</l7:StringValue>
</l7:Property>
</l7:Properties>
</l7:Mapping>
<l7:Mapping action="NewOrUpdate" errorType="TargetNotFound" srcId="63a0c33e8cfe5f22fca4349a9bf3500e" srcUri="https://ESFIDTAPIMGMT31.rci.rogers.ca:9443/restman/1.0/identityProviders/1be05876aa22069adc828b594052758a/groups/63a0c33e8cfe5f22fca4349a9bf3500e" type="GROUP">
<l7:Properties>
<l7:Property key="ErrorMessage">
<l7:StringValue>Could not locate entity: Error looking up identity. Cannot find Identity provider with id: 1be05876aa22069adc828b594052758a. Source Entity: EntityHeader. Name=SSP ESF, id=63a0c33e8cfe5f22fca4349a9bf3500e, description=null, type = GROUP</l7:StringValue>
</l7:Property>
</l7:Properties>
</l7:Mapping>

You're welcome! So from the first error I assume you have an identity provider from DEV and an identity provider from PROD.
This is what might be happening behind the scenes:

Since the mapping action is NewOrUpdate, the mapping from Dev '1be05876aa22069adc828b594052758a' is trying to map to the Prod with id '1be05876aa22069adc828b594052758a'. However it is very likely the the id from prod is different, so since we can't find the id '1be05876aa22069adc828b594052758a' in prod, it attempts to create a new identity provider. During this step, it tries to create an identity provider with the same name, which is not allowed.

To fix this, run the command:
./GatewayMigrationUtility.sh manageMappings --srcName <name-of-identity-provider> --targetName <name-of-identity-provider> --type ID_PROVIDER_CONFIG --action Existing --bundle apiBundle.xml.

- the command above tells the mapping to map using names instead of ids, so when it recognizes it on migratein, it will use that identity provider in prod

After fixing that error, the group error might need a similar command

./GatewayMigrationUtility.sh manageMappings --srcName <name-of-group> --targetName <name-of-group> --type group --action Existing --bundle apiBundle.xml.

And after your manageMapping commands are completed, perform a test migratein to see the results.

Thank you very much it resolved.However what is --srcName and --targetName in this context.Infact i used same name i,e FIP-ESF since i have this identity provider in Dev and in QA too.

./GatewayMigrationUtility.sh manageMappings --srcName <FIP-ESF> --targetName <FIP-ESF> --type ID_PROVIDER_CONFIG --action Existing --bundle apiBundle.xml.

Hi that's great to hear.
src* and target* are ways that we can point the mappings from one Gateway to another.

So in this context, srcName is the name of the mapping from DEV, and targetName is the name of the mapping from PROD. This is very similar to folder mappings, in which we used srcPath (folder path from DEV) and targetPath (folder path from PROD). We also have other variants such as srcRoutingUri and targetRoutingUri for services.

Now, if these are not defined in our mappings, it defaults to using the srcId. This means the GMU will assume that the srcId from DEV matches the targetId from PROD, which is not always the case, hence we need to use the manageMappings command to point them to the right place!

Excellent.Thank you very much resolve.

In dev i have few changes to policy and what to update the same in QA.Then in this case would it be any different i have to do,after running the below do i need to run an --action update?

./GatewayMigrationUtility.sh manageMappings --srcName <FIP-ESF> --targetName <FIP-ESF> --type ID_PROVIDER_CONFIG --action Existing --bundle apiBundle.xml.

Hi Popleys,

Sorry for the delayed reply. Yes you are right. Typically if you have made changes in policies to Dev and you want it to be updated in a QA environment, then your action should be Update. Existing would tell the GMU to use the existing old policy in QA without any changes.